Есть ли способ в Sphinx / Pygments, чтобы подчеркнуть одну или несколько строк кода в литеральных включениях? - PullRequest
Новая
       25

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

8 голосов
/ 18 марта 2010

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

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

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

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

Ответы [ 2 ]

5 голосов
/ 18 апреля 2012

Sphinx теперь имеет директиву emphasize-lines для литералов:

http://sphinx -doc.org / наценка / code.html # включает в себя

2 голосов
/ 27 марта 2010

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

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

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

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

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

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

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

Используя стандартного сфинкса (почти то, что предложил С.Лотт): 

.. 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-

... и используя исправленного сфинкса: 

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

Следовательно, это может быть не совсем то, что вы ищете. Патч создает новый узел для каждого из подсвеченных или не подсвеченных разделов кода. Каждый из них будет представлен Sphinx как отдельный раздел

и 
. Чтобы выйти за рамки этого, вы можете создать таблицу стилей, которая лучше выделит строки с акцентом. Дальнейшим хакам, возможно, придется углубиться в кишки Сфинкса и Пигментов, чтобы прямо на них генерировался цельный подчеркнутый стиль: не тривиально. 

 / НТН
...