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

Примеры кода на 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, но она вызывает ошибку, если файл не найден. Эта же директива лишь выдаёт предупреждение.

Table Of Contents

Previous topic

Разметка уровня параграфа

Next topic

Внутристрочная разметка

This Page