.. highlight:: rest

.. _code-examples:

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

.. index:: pair: code; examples
           single: sourcecode

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

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

   >>> 1 + 1
   2
   >>>

Синтаксическая подсветка осуществляется при помощи `Pygments <http://pygments.org>`_ (если он установлен) и обрабатывается хитрым образом:

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

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

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

     .. highlight:: c

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

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

     .. code-block:: ruby

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

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

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

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

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

Номера строк
^^^^^^^^^^^^

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

   .. highlight:: python
      :linenothreshold: 5

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

Для блоков :rst:dir:`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.'

.. versionchanged:: 1.1
   добавлена ``emphasize-lines``.


Включения
^^^^^^^^^^

.. rst:directive:: .. literalinclude:: filename

   Большие куски текста могут храниться во внешнем файле, содержащем просто текст. Этот файл может быть включён при помощи директивы ``literalinclude``. [1]_ Например, для того, чтобы добавить файл :file:`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``/``?>``.

   .. versionadded:: 0.4.3
      Опция ``encoding``.
   .. versionadded:: 0.6
      Опции ``pyobject``, ``lines``, ``start-after`` и ``end-before``. Поддержка абсолютных имён файлов.
   .. versionadded:: 1.0
      Опции ``prepend``, ``append`` и  ``tab-width``.


.. rubric:: Footnotes

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