4. Дополнительные конструкции разметки¶Additional Markup Constructs

4.1. Разметка метаинформации¶Meta-information markup

sectionauthor

Определяет автора текущего раздела. Аргумент должен содержать имя автора (так, чтобы его можно было использовать для отображения, хотя сейчас это не используется) и адрес электронной почты. Доменная часть адреса должна быть в нижнем регистре. Пример:

.. sectionauthor:: Guido van Rossum <guido@python.org>

В настоящее время эта разметка никак не отображается в выводе, но помогает отслеживать вклад авторов.

4.2. Разметка для модулей¶Module-specific markup

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

:mod:`parrot` -- Dead parrot access
===================================

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

Как видите, модульная разметка состоит из двух директив: директивы module и директивы moduleauthor.

module

Эта директива отмечает начало описания модуля, пакета или подмодуля. Имя должно быть полным (то есть включать имя пакета для подмодулей).

Опция platform, если указана, представляет собой разделённый запятыми список платформ, на которых доступен модуль (если он доступен на всех платформах, опцию следует опустить). Ключи – это короткие идентификаторы; используемые примеры включают «IRIX», «Mac», «Windows» и «Unix». Важно использовать ключ, который уже применялся, когда это уместно.

Опция synopsis должна состоять из одного предложения, описывающего назначение модуля – в настоящее время она используется только в Глобальном указателе модулей.

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

moduleauthor

Директива moduleauthor, которая может появляться несколько раз, указывает авторов кода модуля, так же как sectionauthor указывает автора(ов) фрагмента документации. Она тоже в настоящее время не приводит к какому-либо выводу.

4.3. Информационные единицы¶Information units

Существует ряд директив, используемых для описания конкретных возможностей, предоставляемых модулями. Каждая директива требует одной или нескольких сигнатур для предоставления базовой информации об описываемом объекте, а содержимым должно быть описание. Базовая версия создаёт записи в общем указателе; если запись в указателе не нужна, можно указать флаг опции директивы :noindex:. Следующий пример демонстрирует все возможности этого типа директив:

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

Сигнатуры методов объектов или атрибутов данных должны всегда включать имя типа (.. method:: FileInput.input(...)), даже если из контекста очевидно, к какому типу они относятся; это необходимо для обеспечения согласованных перекрёстных ссылок. Если описываются методы, принадлежащие абстрактному протоколу, например «менеджеры контекста», также следует включать (псевдо-)имя типа, чтобы сделать записи в указателе более информативными.

Директивы:

cfunction

Описывает функцию на C. Сигнатура должна быть приведена как в C, например:

.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

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

Обратите внимание: не нужно экранировать обратной косой чертой звёздочки в сигнатуре, так как они не обрабатываются встроенным анализатором reST.

cmember

Описывает член структуры на C. Пример сигнатуры:

.. cmember:: PyObject* PyTypeObject.tp_bases

Текст описания должен включать диапазон допустимых значений, как следует интерпретировать значение и можно ли его изменять. Ссылки на члены структуры в тексте должны использовать роль member.

cmacro

Описывает «простой» макрос на C. Простые макросы – это макросы, используемые для расширения кода, но не принимающие аргументов, поэтому их нельзя описать как функции. Это не предназначено для определения простых констант. Примеры использования в документации Python включают PyObject_HEAD и Py_BEGIN_ALLOW_THREADS.

ctype

Описывает тип C. Сигнатура должна содержать только имя типа.

cvar

Описывает глобальную C-переменную. Сигнатура должна включать тип, такой, как:

.. cvar:: PyObject* PyClass_Type

data

Описывает глобальные данные в модуле, включая переменные и значения, используемые как «определённые константы». Атрибуты классов и объектов не документируются с помощью этой директивы.

exception

Описывает класс исключения. Сигнатура может, но не обязана, включать скобки с аргументами конструктора.

function

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

.. function:: repeat([repeat=3[, number=1000000]])

Методы объектов не документируются с помощью этой директивы. Связанные методы объектов, помещённые в пространство имён модуля как часть его публичного интерфейса, документируются с её помощью, поскольку в большинстве случаев они эквивалентны обычным функциям.

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

class

Описывает класс. Сигнатура может включать скобки с параметрами, которые будут отображаться как аргументы конструктора.

attribute

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

.. class:: Spam

      Description of the class.

      .. data:: ham

         Description of the attribute.

Также есть возможность документировать атрибут вне директивы класса, например, если документация для разных атрибутов и методов разбита на несколько разделов. В этом случае имя класса следует указывать явно:

.. data:: Spam.eggs

method

Описывает метод объекта. Параметры не должны включать self параметр. Описание должно содержать информацию, аналогичную описанной для function. Эту директиву следует вкладывать в директиву класса, как в примере выше.

opcode

Описывает инструкцию байт-кода Python.

cmdoption

Описывает опцию или переключатель командной строки Python. Имена аргументов опций следует заключать в угловые скобки. Пример:

.. cmdoption:: -m <module>

   Run a module as a script.

envvar

Описывает переменную окружения, которую Python использует или определяет.

Также существует обобщённая версия этих директив:

describe

Эта директива создаёт такое же форматирование, как и описанные выше конкретные, но не создаёт записи в индексе или цели для перекрёстных ссылок. Она используется, например, для описания директив в этом документе. Пример:

.. describe:: opcode

   Describes a Python bytecode instruction.

4.4. Примеры кода¶Showing code examples

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

Для представления интерактивного сеанса необходимо включать приглашения и вывод вместе с кодом Python. После последней строки ввода или вывода не должно быть «лишнего» основного приглашения; вот пример того, как не следует делать:

>>> 1 + 1
2
>>>

Подсветка синтаксиса обрабатывается интеллектуально:

• Для каждого исходного файла существует «язык подсветки». По умолчанию, это 'python', поскольку большинство файлов должно подсвечивать фрагменты Python.

• В режиме подсветки Python интерактивные сеансы распознаются автоматически и подсвечиваются соответствующим образом.

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

  .. highlightlang:: c
  

  Этот язык используется до тех пор, пока не будет встречена следующая директива highlightlang.

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

  • python (по умолчанию)
  • c
  • rest
  • none (без подсветки)

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

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

.. literalinclude:: example.py

Имя файла задаётся относительно пути текущего файла. Специфические для документации файлы включений следует помещать в подкаталог Doc/includes.

4.5. Встроенная разметка¶Inline markup

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

Имена локальных переменных, таких как аргументы функций/методов, являются исключением; их следует просто помечать с помощью *var*.

Для всех остальных ролей нужно писать :rolename:`content`.

Существуют некоторые дополнительные средства, которые делают роли перекрёстных ссылок более гибкими:

• Можно указать явный заголовок и цель ссылки, как в прямых гиперссылках reST: :role:`title <target>` будет ссылаться на target, но текст ссылки будет title.

• Если перед содержимым указать !, ссылка/гиперссылка не будет создана.

• Для ролей объектов Python, если перед содержимым поставить ~, текст ссылки будет содержать только последний компонент цели. Например, :meth:`~Queue.Queue.get` будет ссылаться на Queue.Queue.get, но отображать в качестве текста ссылки только get.

  В HTML-выводе атрибут title ссылки (который, например, отображается как всплывающая подсказка при наведении мыши) всегда будет содержать полное имя цели.

Следующие роли ссылаются на объекты в модулях и, возможно, будут гиперссылками, если будет найден соответствующий идентификатор:

mod

Имя модуля; может использоваться точечное имя. Это также следует использовать для имён пакетов.

func

Имя функции Python; могут использоваться точечные имена. Текст роли не должен включать завершающие круглые скобки для улучшения читаемости. Скобки отбрасываются при поиске идентификаторов.

data

Имя переменной или константы уровня модуля.

const

Имя «определённой» константы. Это может быть #define языка C или переменная Python, которая не предназначена для изменения.

class

Имя класса; может использоваться точечное имя.

meth

Имя метода объекта. Текст роли должен включать имя типа и имя метода. Может использоваться точечное имя.

attr

Имя атрибута данных объекта.

exc

Имя исключения. Может использоваться точечное имя.

Имя, заключённое в эту разметку, может включать имя модуля и/или имя класса. Например, :func:`filter` может ссылаться на функцию с именем filter в текущем модуле или на встроенную функцию с таким именем. В отличие от этого, :func:`foo.filter` явно ссылается на функцию filter в модуле foo.

Обычно имена в этих ролях сначала ищутся без дополнительных уточнений, затем с добавлением имени текущего модуля, затем с добавлением имени текущего модуля и класса (если он есть). Если перед именем поставить точку, порядок меняется на обратный. Например, в документации модуля codecs, :func:`open` всегда ссылается на встроенную функцию, в то время как :func:`.open` ссылается на codecs.open().

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

Следующие роли создают перекрёстные ссылки на конструкции языка C, если они определены в документации API:

cdata

Имя переменной на языке C.

cfunc

Имя функции на языке C. Должно включать завершающие круглые скобки.

cmacro

Имя «простой» C-макроса, как определено выше.

ctype

Имя типа на языке C.

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

token

Имя грамматического токена (используется в справочном руководстве для создания ссылок между отображениями порождающих правил).

Следующая роль создает перекрестную ссылку на термин в глоссарии:

term

Ссылка на термин в глоссарии. Глоссарий создается с помощью директивы glossary, содержащей список определений с терминами и определениями. Он не обязательно должен находиться в том же файле, что и разметка term на самом деле, по умолчанию документация Python имеет один глобальный глоссарий в файле glossary.rst.

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

Следующие роли не делают ничего особенного, кроме форматирования текста в другом стиле:

command

Имя команды уровня ОС, например rm.

dfn

Отмечает определяющее вхождение термина в тексте. (Записи в указателе не создаются.)

envvar

Переменная окружения. Записи в указателе создаются.

file

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

... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

В собранной документации x будет отображаться иначе, чтобы указать, что он должен быть заменен на минорную версию Python.

guilabel

Метки, представленные как часть интерактивного пользовательского интерфейса, должны быть отмечены с помощью guilabel. Это включает метки из текстовых интерфейсов, таких как созданных с использованием curses или других текстовых библиотек. Любая метка, используемая в интерфейсе, должна быть отмечена этой ролью, включая надписи на кнопках, заголовки окон, имена полей, названия меню и пунктов меню и даже значения в списках выбора.

kbd

Отмечает последовательность нажатий клавиш. Форма последовательности клавиш может зависеть от соглашений, специфичных для платформы или приложения. Если соответствующих соглашений нет, названия клавиш-модификаторов следует писать полностью, чтобы улучшить доступность для новых пользователей и неносителей языка. Например, последовательность клавиш xemacs может быть отмечена как :kbd:`C-x C-f`, но без ссылки на конкретное приложение или платформу та же последовательность должна быть отмечена как :kbd:`Control-x Control-f`.

keyword

Имя ключевого слова в Python.

mailheader

Имя почтового заголовка в стиле RFC 822. Эта разметка не подразумевает, что заголовок используется в сообщении электронной почты, но может использоваться для ссылки на любой заголовок того же «стиля». Она также используется для заголовков, определенных различными спецификациями MIME. Имя заголовка должно вводиться так же, как оно обычно встречается на практике, с предпочтением соглашений верблюжьего регистра, если существует более одного распространенного варианта. Например: :mailheader:`Content-Type`.

makevar

Имя переменной make.

manpage

Ссылка на страницу руководства Unix, включая раздел, например :manpage:`ls(1)`.

menuselection

Пункты меню следует отмечать с помощью роли menuselection. Она используется для разметки полной последовательности выбора пунктов меню, включая выбор подменю и выбор конкретной операции, или любой подпоследовательности такой последовательности. Названия отдельных пунктов должны разделяться -->.

Например, чтобы отметить выбор «Пуск > Программы», используйте эту разметку:

:menuselection:`Start --> Programs`

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

mimetype

Название MIME-типа или его компонента (основной или вспомогательной части, взятой отдельно).

newsgroup

Название группы новостей Usenet.

option

Параметр командной строки Python. Начальный дефис (или дефисы) должны быть включены. Если существует соответствующая директива cmdoption, ссылка ведёт на неё. Для параметров других программ или сценариев используйте простую разметку ``code``.

program

Название исполняемой программы. Оно может отличаться от имени файла исполняемого файла на некоторых платформах. В частности, расширение .exe (или другое) следует опускать для программ Windows.

regexp

Регулярное выражение. Кавычки не следует включать.

samp

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

Если не требуется указание «переменной» части, используйте стандартную разметку ``code``.

var

Имя переменной или параметра Python или C.

Следующие роли создают внешние ссылки:

pep

Ссылка на предложение по улучшению Python (PEP). Она создаёт соответствующие элементы индекса. Генерируется текст «PEP number»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного PEP.

rfc

Ссылка на RFC (Internet Request for Comments). Она создаёт соответствующие элементы индекса. Генерируется текст «RFC number»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного RFC.

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

4.6. Разметка перекрёстных ссылок¶Cross-linking markup

Для поддержки перекрёстных ссылок на произвольные разделы документации, стандартные метки reST используются несколько нестандартно: каждая метка должна предшествовать заголовку раздела, и каждое имя метки должно быть уникальным во всём исходном тексте документации.

Затем можно ссылаться на эти разделы с помощью роли :ref:`label-name`.

Пример:

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

Вызов :ref: заменяется заголовком раздела.

4.7. Разметка уровня абзаца¶Paragraph-level markup

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

note

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

Пример:

.. note::

   This function is not suitable for sending spam e-mails.

warning

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

versionadded

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

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

Пример:

.. versionadded:: 3.1
   The *spam* parameter.

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

versionchanged

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

impl-detail

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

.. impl-detail::

   This describes some implementation detail.

   More explanation.

или

.. impl-detail:: This shortly mentions an implementation detail.

«Детали реализации CPython:» автоматически добавляется перед содержимым.

seealso

Во многих разделах есть списки ссылок на документацию модулей или внешние документы. Эти списки создаются с помощью директивы смотри также.

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

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

.. seealso::

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

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

rubric

Эта директива создаёт заголовок абзаца, который не используется для создания узла оглавления. В настоящее время она применяется для заголовка «Сноски».

centered

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

.. centered::

   Paragraph contents.

4.8. Разметка оглавления¶Table-of-contents markup

Поскольку в reST нет средств для взаимосвязи нескольких документов или разделения документов на несколько выходных файлов, Sphinx использует специальную директиву для добавления связей между отдельными файлами, из которых состоит документация, а также для оглавлений. Директива toctree является центральным элементом.

toctree

Эта директива вставляет «дерево оглавления» в текущее место, используя отдельные оглавления (включая «поддеревья оглавления») файлов, указанных в теле директивы. Можно указать числовой параметр maxdepth, чтобы задать глубину дерева; по умолчанию включаются все уровни.

Рассмотрим этот пример (взятый из указателя библиотечных ссылок):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

Это делает две вещи:

• Вставляются оглавления всех этих файлов с максимальной глубиной два, то есть один вложенный заголовок. Директивы toctree в этих файлах также учитываются.
• Sphinx знает относительный порядок файлов intro, strings и так далее, а также то, что они являются дочерними по отношению к показанному файлу – указателю библиотеки. На основе этой информации генерируются ссылки «следующая глава», «предыдущая глава» и «родительская глава».

В конечном итоге все файлы, включённые в процесс сборки, должны присутствовать в одной директиве toctree; Sphinx выдаст предупреждение, если обнаружит файл, который не включён, поскольку это означает, что данный файл будет недоступен через стандартную навигацию.

Специальный файл contents.rst в корне исходного каталога является «корнем» иерархии дерева оглавления; на его основе генерируется страница «Содержание».

4.9. Разметка для генерации индекса¶Index-generating markup

Sphinx автоматически создаёт записи индекса для всех информационных единиц (таких как функции, классы или атрибуты), как уже обсуждалось.

Однако есть и явная директива, которая делает индекс более полным и позволяет добавлять записи индекса в документы, где информация не сосредоточена в информационных единицах, – например, в справочнике по языку.

Директива называется index и содержит одну или несколько записей индекса. Каждая запись состоит из типа и значения, разделённых двоеточием.

Например:

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

Эта директива содержит пять записей, которые будут преобразованы в записи генерируемого индекса, ссылающиеся на точное местоположение указания индекса (или, в случае офлайн-носителей, на соответствующий номер страницы).

Возможные типы записей:

single

Создаёт одну запись индекса. Может быть преобразована в подзапись: текст подзаписи отделяется точкой с запятой (это же обозначение используется ниже для описания создаваемых записей).

pair

pair: loop; statement – это сокращение, которое создаёт две записи индекса, а именно loop; statement и statement; loop.

triple

Аналогично, triple: module; search; path – это сокращение, которое создаёт три записи индекса: module; search path, search; path, module и path; module search.

модуль, ключевое слово, оператор, объект, исключение, инструкция, встроенная функция

Все они создают по две записи индекса. Например, module: hashlib создаёт записи module; hashlib и hashlib; module.

Для директив индекса, содержащих только записи типа «single», существует сокращённая запись:

.. index:: BNF, grammar, syntax, notation

Это создаёт четыре записи индекса.

4.10. Отображение грамматических продукций¶Grammar production displays

Для отображения продукций формальной грамматики доступна специальная разметка. Она проста и не пытается моделировать все аспекты БНФ (или любых производных форм), но предоставляет достаточно возможностей, чтобы контекстно-свободные грамматики отображались так, что использование символа показывает гиперссылку на его определение. Существует следующая директива:

productionlist

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

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

Определение может содержать имена токенов, которые помечены как интерпретируемый текст (например, unaryneg ::= "-" `integer`) – это создаёт перекрёстные ссылки на продукции этих токенов.

Обратите внимание, что в продукции не выполняется дальнейший разбор reST, поэтому не нужно экранировать символы * или |.

Ниже приведён пример из Справочного руководства по Python:

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

4.11. Подстановки¶Substitutions

Система документации предоставляет три подстановки, определённые по умолчанию. Они задаются в файле конфигурации сборки conf.py.

|release|

Заменяется на версию Python, к которой относится документация. Это полная строка версии, включающая теги альфа/бета/кандидата на выпуск, например 2.5.2b3.

|version|

Заменяется на номер версии Python, к которой относится документация. Он состоит только из major и minor частей версии, например 2.5, даже для версии 2.5.1.

|today|

Заменяется либо на сегодняшнюю дату, либо на дату, указанную в файле конфигурации сборки. Обычно имеет формат April 14, 2007.

Сноски