Показ примеров кода

Примеры кода на Python или интерактивные сессии являются обычными литеральными блоками reST. Они начинаютя с :: в конце предыдущего параграфа и выделяются отступами.

Представление интерактивных сессии требует включения приглашения и вывода, кроме самого кода Python. Никакой специальной разметки для этого не требуется. После последней строки вывода не должно быть “ненужного” приглашения. Вот пример того, что быть не должно:

>>> 1 + 1
2
>>>

Синтаксическая подсветка осуществляется при помощи Pygments (если он установлен) и обрабатывается хитрым образом:

  • Есть “подсвечиваемый язык” для каждого файла. По умолчанию, это 'python', так как большая часть файлов будет содержать примеры кода на Python, но настройки для документации в общем могут быть заданы при помощи конфигурационного значения :confval:`highlight_language`.

  • В режиме подсветки Python, интерактивные сессии распознаются автоматически и соответсвенно подсвечиваются. Обычный код Python подсвечивается только в случае, если его можно разобрать (так что Вы можете использовать Python в качестве умолчания, а разбросанные вставки кода на шелле или чём-то другом не будут подсвечены).

  • Подсвечиваемый язык может быть изменён при помощи директивы, которая используется следующим образом:

    .. highlight:: c

    Этот язык будет использоваться до следующей диркетивы highlight.

  • Для документов, которые должны показывать код на разных языках, существует директива code-block, которая явно указывает язык подсветки:

    .. code-block:: ruby

   Некоторый код на Ruby.

    Можно использовать её синоним sourcecode.

  • Допустимые значения для подсвечиваемых языков:

    • none (без подсветки)
    • python (значение по умолчанию, если :confval:`highlight_language` не задан)
    • guess (пусть Pygments сам догадается о языке на осовании контекста. Работает только с некоторыми хорошо распознаваемыми языками)
    • rest
    • c
    • ... и другие языки, которые поддерживаются Pygments.

  • Если подсветка для определённого языка не срабатывает - то блок вообще не будет подсвечен.

Номера строк

Если установлен, Pygments может пронумеровать строки кода. Для автоматически подсвечиваемых блоков (которые начинаются с ::), нумерация строк определяется в директиве highlight при помощи опции linenothreshold:

.. highlight:: python
   :linenothreshold: 5

Такой код будет нумеровать все куски кода, содержащие больше чем 5 сток.

Для блоков code-block, флаг linenos включает нумерацию строк для этого конкретного блока:

.. code-block:: ruby
   :linenos:

   Некий код на Ruby.

Кроме того, можно использовать опцию emphasize-lines, которая приведёт к тому, что Pygments выделит определённые строки:

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

Changed in version 1.1: добавлена emphasize-lines.

Включения

.. literalinclude:: filename

Большие куски текста могут храниться во внешнем файле, содержащем просто текст. Этот файл может быть включён при помощи директивы literalinclude. [1] Например, для того, чтобы добавить файл example.py с кодом Python используйте:

.. literalinclude:: example.py

Имя файла обычно является относительным текущего файла. Однако, если оно абсолютное (начинается с /), то оно рассматривается относительно исходного каталога.

Табы в выводе преобразуются при помощи опции tab-width, которая задаёт ширину табуляции.

Директива так же поддерживает флаг опции linenos для отображения номеров строк, опцию emphasize-lines для выделения некоторых строк и опцию language для задания языка, отличного от текущего языка фала. Вот пример:

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

Вклюаемые файлы должны быть в кодировке :confval:`source_encoding`. Если кодировка отличается, то Вы можете задать её при помощи опции encoding:

.. literalinclude:: example.py
   :encoding: latin-1

Эта директива так же поддерживает включение только части файла. Если это модуль Python, то Вы можете определить класс, функцию или метод, который хотите включить при помощи опции pyobject:

.. literalinclude:: example.py
   :pyobject: Timer.start

Эта директива включит только код, который относится к методу start() класса Timer из этого файла.

Кроме того, Вы можете указать строки, которые должны быть включены при помощи опции lines:

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

Таким образом Вы включите строки 1, 3, с 5 по 10 и с 20 строки до конца файла.

Другой способ указать часть файла для включения - использовать опции start-after и end-before (или одну из них). Если используется опция start-after, то будут включены только строки, которые расположены за строкой, содержащей аргумент этой опции. Если используется опция end-before, то будут включены только строки, расположенные до первой строки, содержащей аргумент опции.

Вы можете вставить строку в начало или конец включаемого кода при помощи опций prepend и append соответственно. Это полезно для подсветки кода PHP, который не содержит маркеров <?php/?>.

New in version 0.4.3: Опция encoding.

New in version 0.6: Опции pyobject, lines, start-after и end-before. Поддержка абсолютных имён файлов.

New in version 1.0: Опции prepend, append и tab-width.

Footnotes

[1]Есть стандартная директива .. include, но она вызывает ошибку, если файл не найден. Эта же директива лишь выдаёт предупреждение.