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

Эти директивы создают короткие параграфы и могут быть использованы в информационных разделах, так же как и обычный текст:

.. note::

Особо важная информация об API, о которой нужно предупредить пользователя. Содержимое этой директивы должно быть написано как любой обычный текст.

Пример:

.. note::

   Эта функция не подходит для отправки спама.
.. warning::

Особо важная информация об API, о которой нужно предупредить пользователя. Содержимое этой директивы должно быть написано как любой обычный текст. Отличие от note в том, что эта директива больше подходит для информации о безопасности.

.. versionadded:: version

Эта директива указывает версию для проекта, в которой была добавлена описываемая возможность в библиотеку или в C API. Когда это относится ко всему модулю, она должна быть расположена вверху модуля перед любой другой информацией.

Первый аргумент обязателен и указывает версию; во втором аргументе Вы можете поместить краткое объясненеие изменения.

Пример:

.. versionadded:: 2.5
   Параметр *spam*.

Обратите внимание, что не должно быть никаких пустых строк между директивой и объяснением; благодаря этому этот блок выглядит единым в разметке.

.. versionchanged:: version

Похоже на versionadded, но описывает когда и что изменилось в указанной функциональности (новые параметры, побочные эффекты и т.д.).

.. deprecated:: version

Похоже на versionchanged, но описывает с какой версии эта функциональность нежелательна. Можно так же указать объяснение, например, информацию о том, что надо использовать вместо старой функциональности. Например:

.. deprecated:: 3.1
   Вместо этого используйте :func:`spam`.
.. seealso::

Многие разделы включают список ссылок на документацю модуля или внешние документы. Этот список создаётся при помощи директивы seealso.

Директива seealso обычно располагается в разделе перед любыми подразделами. Для HTML вывода, он помещается в рамку отдельно от основного текста.

Содержимое директивы seealso должно быть списком определения reST. Например:

.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

Кроме того, есть “короткая форма”, которая позволяет задать его таким образом:

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

New in version 0.5: Короткая форма.

.. rubric:: title

Эта директива создаёт заголовок параграфа, котоырй не используется для создания элемента содержания.

Note

Если title раздела указан “Footnotes” (или эквивалент, на выбранном языке), этот раздел игнорируется LaTeX writer, так как он должен содержать только определения ссылок и создаёт пустой заголовок.

.. centered::

Эта директива создаёт центрированную строку жирного текста. Используйте его таким образом:

.. centered:: LICENSE AGREEMENT

Deprecated since version 1.1: Эта директива отображения является наследие старых версий. Вместо неё используйте директиву rst-class и добавьте соответствующий стиль.

.. hlist::

Эта директива должна содержать список. Он будет преобразован в более компактный список, либо расположив несколько списков горизонтально, либо сокращая простарнство между элементами, в зависимости от “сборщика”.

Для “сборщиков”, которые поддерживают горизонтальное расположение, есть опция columns, которая задаёт количество колонок; по умоланию 2. Например:

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

New in version 0.6.

Разметка содержания

Директива toctree, котрая создаёт содержание поддокументов, описана в Содержание (TOC tree).

Для локальных содержаний используйте стандартную директиву reST :dudir:`contents directive <table-of-contents>`.

Словарь

.. glossary::

Эта директива должна содержать разметку словаря reST с терминами и определениями. На определения можно будет делать сноски при помощи роли term. Например:

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

В отличие от обычного списка определений, тут можно использовать несколько терминов для одного определения и можно использвать внутритекстовую разметку. Вы можете создать ссылку на все термины. Например:

.. glossary::

   term 1
   term 2
      Definition of both terms.

(Если словарь отсортирован, то первый термин определяет порядок сортировки.)

New in version 0.6: Вы можете добавить флаг :sorted:, который будет автоматически сортировать элементы по алфавиту.

Changed in version 1.1: Теперь поддерживает несклько терминов и внутренную разметку для терминов.

Отображение формальной грамматики

Специальная разметка предназначена для отображения формальной грамматики. Эта разметка проста и не учитывает все аспекты формы Бэкуса — Наура (или её производных), но позволяет отображать грамматику так, чтобы символ отображался как ссылка на его определение. Вот эта директива:

.. productionlist:: [name]

Эта директива используется для описания группы определений. Каждое определения задаётся на отдельной строке и состоит из имени, отделённого двоеточием от определения. Если определение содержит несколько строк, то каждая следующая строка должна начинаться с двоеточия в той же колонке, что и на первой строке определения.

Аргумент productionlist служит для различия наборов списков, которые принадлежат различным грамматикам.

В аргументах директивы productionlist не допустимы пустые строки.

Определение может содержать имена, которые будут отмечены, как интерпретированный текст (т.е. sum ::= `integer` "+" `integer`) – это создаст кросс-сылки на определения этих имён. За пределами списка Вы можете ссылаться на определения при помощи token.

Обратите внимание, что никакого парсинга reST далее не происходит, так что не нужно экранировать символы * или |.

Вот пример из Python Reference Manual:

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`