Существует ли путь в Sphinx/Pygments, чтобы подчеркнуть, что одна или несколько строк кода в литерале включают?

Question

Существует ли путь в Sphinx/Pygments, чтобы подчеркнуть, что одна или несколько строк кода в литерале включают?

В некоторых документах сфинкса я пишу, я включаю примеры кода из вспомогательного файла как так:

.. literalinclude:: mymodule.py
   :pyobject: MyClass
   :linenos:

Этот конкретный документ является учебным руководством, где классы являются наращиванием шаг за шагом. То, что я хотел бы сделать, включают весь класс или отдельный метод, и подчеркивают только строки интереса для того раздела. Тем путем контекст сохраняется, но интересные части очевидны сразу. Прямо сейчас я обратился только к обращению к номерам строки в тексте, который в порядке, но далекий от идеала.

При рассмотрении документов и кода для сфинкса и пигментов я не нахожу очевидный способ сделать это. Я не настроен против исправления их или выполнения чего-то хитрого в conf.py, но я задался вопросом, решил ли кто-либо это.

8

python documentation-generation python-sphinx pygments

задан Chris Morgan 18 July 2011 в 13:13

1 ответ

Другие вопросы по тегам:

python documentation-generation python-sphinx pygments

Похожие вопросы:

score 2 · Answer 1

Вы можете исправить директиву LiteralInclude в sphinx/directives/code.py

Там вам нужно будет сделать что-то такое, чтобы при включении кода вы могли указать начальную/конечную строку, чтобы подчеркнуть ее в этом фрагменте.
Второй шаг потребует создания некоторых способов разного выделения. Самый простой подход заключается в том, что часть без подчеркивания не выделяется, а часть с подчеркиванием выделяется. Это позволит избежать более сложного взлома стилей и выделения.

Это дает, например, новую опцию lines-emphasis в директиве literalinclude, которую можно использовать следующим образом:

.. literalinclude:: ../sphinx/directives/code.py
   :pyobject: Highlight
   :lines-emphasis: 6,13

где line-emphasis - начальная строка, конечная строка относительно включаемого кода, первая строка - 1.

Используя sphinx 0.6.5 на pypi.python.org/pypi/Sphinx/0.6.5 в качестве основы, можно быстро исправить code.py: http://paste.pocoo.org/show/194456/

Обратите внимание, что следующее было бы эквивалентно:

Использование стандартного sphinx (практически то, что предложил S.Lott):

.. literalinclude:: ../sphinx/directives/code.py
   :language: none
   :lines: 0-36
.. literalinclude:: ../sphinx/directives/code.py
   :lines: 36-46
.. literalinclude:: ../sphinx/directives/code.py
   :language: none
   :lines: 37-

... и использование исправленного sphinx:

.. literalinclude:: ../sphinx/directives/code.py
   :lines-emphasis: 37,47

Поэтому это может быть не совсем то, что вы ищете. Патч создает новый узел для каждого из выделенных или не выделенных участков кода. Каждый из них будет отображаться Sphinx как отдельный раздел < div > и < pre >. Чтобы пойти дальше, вы можете создать таблицу стилей, которая будет лучше выделять строки с подчеркиванием. Дальнейшие хаки могут потребовать глубокого проникновения в внутренности Sphinx и Pygments, чтобы иметь бесшовный подчеркнутый стиль, генерируемый непосредственно там: это не тривиально.

/HTH