markup.md
1> **Источник:** https://python-all.ru/3.0/documenting/markup.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Дополнительные конструкции разметки89Sphinx добавляет множество новых директив и интерпретируемых текстовых ролей к стандартной разметке reST. В этом разделе содержится справочная информация об этих средствах. Документация по «стандартным» конструкциям reST здесь не приводится, хотя они используются в документации Python.1011> **Примечание**12>13> Это лишь обзор расширенных возможностей разметки Sphinx; полное описание можно найти в [его собственной документации](https://python-all.ru/3.0/documenting/markup.html).1415## Разметка метаинформации1617#### `sectionauthor`1819Определяет автора текущего раздела. Аргумент должен содержать имя автора (так, чтобы его можно было использовать для отображения, хотя сейчас это не используется) и адрес электронной почты. Доменная часть адреса должна быть в нижнем регистре. Пример:2021```rest22.. sectionauthor:: Guido van Rossum <guido@python.org>23```2425В настоящее время эта разметка никак не отображается в выводе, но помогает отслеживать вклад авторов.2627## Разметка для модулей2829Разметка, описанная в этом разделе, используется для предоставления информации о документируемом модуле. Каждый модуль следует документировать в отдельном файле. Обычно эта разметка располагается после заголовка файла; типичный файл может начинаться так:3031```rest32:mod:`parrot` -- Dead parrot access33===================================3435.. module:: parrot36 :platform: Unix, Windows37 :synopsis: Analyze and reanimate dead parrots.38.. moduleauthor:: Eric Cleese <eric@python.invalid>39.. moduleauthor:: John Idle <john@python.invalid>40```4142Как видите, модульная разметка состоит из двух директив: директивы `module` и директивы `moduleauthor`.4344#### `module`4546Эта директива отмечает начало описания модуля (или подмодуля пакета; в этом случае имя должно быть полностью квалифицированным, включая имя пакета).4748Опция `platform`, если указана, представляет собой разделённый запятыми список платформ, на которых доступен модуль (если он доступен на всех платформах, опцию следует опустить). Ключи – это короткие идентификаторы; используемые примеры включают «IRIX», «Mac», «Windows» и «Unix». Важно использовать ключ, который уже применялся, когда это уместно.4950Опция `synopsis` должна состоять из одного предложения, описывающего назначение модуля – в настоящее время она используется только в Глобальном указателе модулей.5152Опция `устарело` может быть указана (без значения), чтобы пометить модуль как устаревший; затем он будет обозначен как таковой в различных местах.5354#### `moduleauthor`5556Директива5758`moduleauthor`5960, которая может появляться несколько раз, указывает авторов кода модуля, так же как6162`sectionauthor`6364указывает автора(ов) фрагмента документации. Она тоже в настоящее время не приводит к какому-либо выводу.6566> **Примечание**67>68> Важно сделать заголовок раздела файла, описывающего модуль, осмысленным, поскольку это значение будет вставлено в деревья оглавления в обзорных файлах.6970## Информационные единицы7172Существует ряд директив, используемых для описания конкретных возможностей, предоставляемых модулями. Каждая директива требует одной или нескольких сигнатур для предоставления базовой информации об описываемом объекте, а содержимым должно быть описание. Базовая версия создаёт записи в общем указателе; если запись в указателе не нужна, можно указать флаг опции директивы `:noindex:`. Следующий пример демонстрирует все возможности этого типа директив:7374```rest75.. function:: spam(eggs)76 ham(eggs)77 :noindex:7879 Spam or ham the foo.80```8182Сигнатуры методов объектов или атрибутов данных должны всегда включать имя типа (`.. method:: FileInput.input(...)`), даже если из контекста очевидно, к какому типу они относятся; это необходимо для обеспечения согласованных перекрёстных ссылок. Если описываются методы, принадлежащие абстрактному протоколу, например «менеджеры контекста», также следует включать (псевдо-)имя типа, чтобы сделать записи в указателе более информативными.8384Директивы:8586#### `cfunction`8788Описывает функцию на C. Сигнатура должна быть приведена как в C, например:8990```rest91.. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)92```9394Это также используется для описания макросов препроцессора, похожих на функции. Имена аргументов должны быть указаны, чтобы их можно было использовать в описании.9596Обратите внимание: не нужно экранировать обратной косой чертой звёздочки в сигнатуре, так как они не обрабатываются встроенным анализатором reST.9798#### `cmember`99100Описывает член структуры на C. Пример сигнатуры:101102```rest103.. cmember:: PyObject* PyTypeObject.tp_bases104```105106Текст описания должен включать диапазон допустимых значений, как следует интерпретировать значение и можно ли его изменять. Ссылки на члены структуры в тексте должны использовать роль `member`.107108#### `cmacro`109110Описывает «простой» макрос на C. Простые макросы – это макросы, используемые для расширения кода, но не принимающие аргументов, поэтому их нельзя описать как функции. Это не предназначено для определения простых констант. Примеры использования в документации Python включают111112[`PyObject_HEAD`](https://python-all.ru/3.0/c-api/structures.html#PyObject_HEAD)113114и115116[`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.0/c-api/init.html#Py_BEGIN_ALLOW_THREADS)117118.119120#### `ctype`121122Описывает тип C. Сигнатура должна содержать только имя типа.123124#### `cvar`125126Описывает глобальную C-переменную. Сигнатура должна включать тип, такой, как:127128```rest129.. cvar:: PyObject* PyClass_Type130```131132#### `data`133134Описывает глобальные данные в модуле, включая переменные и значения, используемые как «определённые константы». Атрибуты классов и объектов не документируются с помощью этого окружения.135136#### `exception`137138Описывает класс исключения. Сигнатура может, но не обязана, включать скобки с аргументами конструктора.139140#### `function`141142Описывает функцию уровня модуля. Сигнатура должна включать параметры, заключая необязательные параметры в квадратные скобки. Значения по умолчанию можно указывать, если это улучшает понимание. Например:143144```rest145.. function:: Timer.repeat([repeat=3[, number=1000000]])146```147148Методы объектов не документируются с помощью этой директивы. Связанные методы объектов, помещённые в пространство имён модуля как часть его публичного интерфейса, документируются с её помощью, поскольку в большинстве случаев они эквивалентны обычным функциям.149150Описание должно включать информацию о требуемых параметрах и способах их использования (в особенности, изменяются ли передаваемые изменяемые объекты), побочных эффектах и возможных исключениях. Может быть приведён небольшой пример.151152#### `class`153154Описывает класс. Сигнатура может включать скобки с параметрами, которые будут отображаться как аргументы конструктора.155156#### `attribute`157158Описывает атрибут данных объекта. Описание должно включать информацию об ожидаемом типе данных и о том, можно ли его изменять напрямую.159160#### `method`161162Описывает метод объекта. Параметры не должны включать параметр163164`self`165166. Описание должно содержать информацию, аналогичную описанной для167168`function`169170.171172#### `opcode`173174Описывает инструкцию175176[*байт-кода*](https://python-all.ru/3.0/glossary.html#term-bytecode)177178Python.179180#### `cmdoption`181182Описывает опцию или переключатель командной строки. Имена аргументов опций должны заключаться в угловые скобки. Пример:183184```rest185.. cmdoption:: -m <module>186187 Run a module as a script.188```189190#### `envvar`191192Описывает переменную окружения, которую Python использует или определяет.193194Также существует обобщённая версия этих директив:195196#### `describe`197198Эта директива создаёт такое же форматирование, как и описанные выше конкретные, но не создаёт записи в индексе или цели для перекрёстных ссылок. Она используется, например, для описания директив в этом документе. Пример:199200```rest201.. describe:: opcode202203 Describes a Python bytecode instruction.204```205206## Показ примеров кода207208Примеры исходного кода Python или интерактивных сеансов представляются с помощью стандартных буквальных блоков reST. Они начинаются с `::` в конце предыдущего абзаца и выделяются отступом.209210Для представления интерактивного сеанса необходимо включать приглашения и вывод вместе с кодом Python. После последней строки ввода или вывода не должно быть «лишнего» основного приглашения; вот пример того, как *не* следует делать:211212```rest213>>> 1 + 12142215>>>216```217218Подсветка синтаксиса обрабатывается интеллектуально:219220- Для каждого исходного файла существует «язык подсветки». По умолчанию, это `'python'`, поскольку большинство файлов должно подсвечивать фрагменты Python.221- В режиме подсветки Python интерактивные сеансы распознаются автоматически и подсвечиваются соответствующим образом.222- Язык подсветки можно изменить с помощью директивы `highlightlang`, используемой следующим образом:223224 ```rest225 .. highlightlang:: c226 ```227228 Этот язык используется до тех пор, пока не будет встречена следующая директива `highlightlang`.229- Обычно используемые значения для языка подсветки:230231 - `python` (по умолчанию)232 - `c`233 - `rest`234 - `none` (без подсветки)235- Если подсветка с текущим языком не работает, блок не подсвечивается никаким образом.236237Длинные примеры буквального текста можно включать, сохранив пример в отдельном файле, содержащем только обычный текст. Файл можно подключить с помощью директивы `literalinclude`. [\[1\]](https://python-all.ru/3.0/documenting/markup.html#id2) Например, чтобы включить исходный файл Python `example.py`, используйте:238239```rest240.. literalinclude:: example.py241```242243Имя файла задаётся относительно пути текущего файла. Специфические для документации файлы включений следует помещать в подкаталог `Doc/includes`.244245## Встроенная разметка246247Как уже говорилось, Sphinx использует интерпретируемые текстовые роли для вставки семантической разметки в документы.248249Имена переменных являются исключением; их следует помечать просто `*var*`.250251Для всех остальных ролей нужно писать `` :rolename:`content` ``.252253Существуют некоторые дополнительные средства, которые делают роли перекрёстных ссылок более гибкими:254255- Можно указать явный заголовок и цель ссылки, как в прямых гиперссылках reST: `` :role:`title <target>` `` будет ссылаться на *target*, но текст ссылки будет *title*.256- Если перед содержимым указать `!`, ссылка/гиперссылка не будет создана.257- Для ролей объектов Python, если перед содержимым поставить `~`, текст ссылки будет содержать только последний компонент цели. Например, `` :meth:`~Queue.Queue.get` `` будет ссылаться на `Queue.Queue.get`, но отображать в качестве текста ссылки только `get`.258259 В HTML-выводе атрибут `title` ссылки (который, например, отображается как всплывающая подсказка при наведении мыши) всегда будет содержать полное имя цели.260261Следующие роли ссылаются на объекты в модулях и, возможно, будут гиперссылками, если будет найден соответствующий идентификатор:262263#### `mod`264265Имя модуля; может использоваться точечное имя. Это также следует использовать для имён пакетов.266267#### `func`268269Имя функции Python; могут использоваться точечные имена. Текст роли не должен включать завершающие круглые скобки для улучшения читаемости. Скобки отбрасываются при поиске идентификаторов.270271#### `data`272273Имя переменной уровня модуля.274275#### `const`276277Имя «определённой» константы. Это может быть278279`#define`280281языка C или переменная Python, которая не предназначена для изменения.282283#### `class`284285Имя класса; может использоваться точечное имя.286287#### `meth`288289Имя метода объекта. Текст роли должен включать имя типа и имя метода. Может использоваться точечное имя.290291#### `attr`292293Имя атрибута данных объекта.294295#### `exc`296297Имя исключения. Может использоваться точечное имя.298299Имя, заключённое в эту разметку, может включать имя модуля и/или имя класса. Например, `` :func:`filter` `` может ссылаться на функцию с именем `filter` в текущем модуле или на встроенную функцию с таким именем. В отличие от этого, `` :func:`foo.filter` `` явно ссылается на функцию `filter` в модуле `foo`.300301Обычно имена в этих ролях сначала ищутся без дополнительных уточнений, затем с добавлением имени текущего модуля, затем с добавлением имени текущего модуля и класса (если он есть). Если перед именем поставить точку, порядок меняется на обратный. Например, в документации модуля [`codecs`](https://python-all.ru/3.0/library/codecs.html#module-codecs), `` :func:`open` `` всегда ссылается на встроенную функцию, в то время как `` :func:`.open` `` ссылается на [`codecs.open()`](https://python-all.ru/3.0/library/codecs.html#codecs.open).302303Похожая эвристика используется для определения, является ли имя атрибутом текущего документируемого класса.304305Следующие роли создают перекрёстные ссылки на конструкции языка C, если они определены в документации API:306307#### `cdata`308309Имя переменной на языке C.310311#### `cfunc`312313Имя функции на языке C. Должно включать завершающие круглые скобки.314315#### `cmacro`316317Имя «простой» C-макроса, как определено выше.318319#### `ctype`320321Имя типа на языке C.322323Следующая роль, возможно, создает перекрестную ссылку, но не ссылается на объекты:324325#### `token`326327Имя грамматического токена (используется в справочном руководстве для создания ссылок между отображениями порождающих правил).328329Следующая роль создает перекрестную ссылку на термин в глоссарии:330331#### `term`332333Ссылка на термин в глоссарии. Глоссарий создается с помощью директивы `glossary`, содержащей список определений с терминами и определениями. Он не обязательно должен находиться в том же файле, что и разметка `term` на самом деле, по умолчанию документация Python имеет один глобальный глоссарий в файле `glossary.rst`.334335Если используется термин, не объясненный в глоссарии, при сборке будет выдано предупреждение.336337---338339Следующие роли не делают ничего особенного, кроме форматирования текста в другом стиле:340341#### `command`342343Имя команды уровня ОС, например344345`rm`346347.348349#### `dfn`350351Отмечает определяющее вхождение термина в тексте. (Записи в указателе не создаются.)352353#### `envvar`354355Переменная окружения. Записи в указателе создаются.356357#### `file`358359Имя файла или каталога. В содержимом можно использовать фигурные скобки для обозначения «переменной» части, например:360361```rest362... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...363```364365В собранной документации `x` будет отображаться иначе, чтобы указать, что он должен быть заменен на минорную версию Python.366367#### `guilabel`368369Метки, представленные как часть интерактивного пользовательского интерфейса, должны быть отмечены с помощью370371`guilabel`372373. Это включает метки из текстовых интерфейсов, таких как созданных с использованием374375[`curses`](https://python-all.ru/3.0/library/curses.html#module-curses)376377или других текстовых библиотек. Любая метка, используемая в интерфейсе, должна быть отмечена этой ролью, включая надписи на кнопках, заголовки окон, имена полей, названия меню и пунктов меню и даже значения в списках выбора.378379#### `kbd`380381Отмечает последовательность нажатий клавиш. Форма последовательности клавиш может зависеть от соглашений, специфичных для платформы или приложения. Если соответствующих соглашений нет, названия клавиш-модификаторов следует писать полностью, чтобы улучшить доступность для новых пользователей и неносителей языка. Например, последовательность клавиш382383*xemacs*384385может быть отмечена как386387`` :kbd:`C-x C-f` ``388389, но без ссылки на конкретное приложение или платформу та же последовательность должна быть отмечена как390391`` :kbd:`Control-x Control-f` ``392393.394395#### `keyword`396397Имя ключевого слова в Python.398399#### `mailheader`400401Имя почтового заголовка в стиле RFC 822. Эта разметка не подразумевает, что заголовок используется в сообщении электронной почты, но может использоваться для ссылки на любой заголовок того же «стиля». Она также используется для заголовков, определенных различными спецификациями MIME. Имя заголовка должно вводиться так же, как оно обычно встречается на практике, с предпочтением соглашений верблюжьего регистра, если существует более одного распространенного варианта. Например:402403`` :mailheader:`Content-Type` ``404405.406407#### `makevar`408409Имя переменной410411**make**412413.414415#### `manpage`416417Ссылка на страницу руководства Unix, включая раздел, например418419`` :manpage:`ls(1)` ``420421.422423#### `menuselection`424425Пункты меню следует отмечать с помощью роли `menuselection`. Она используется для разметки полной последовательности выбора пунктов меню, включая выбор подменю и выбор конкретной операции, или любой подпоследовательности такой последовательности. Названия отдельных пунктов должны разделяться `-->`.426427Например, чтобы отметить выбор «Пуск \> Программы», используйте эту разметку:428429```rest430:menuselection:`Start --> Programs`431```432433При включении выбора, который содержит завершающий индикатор, например многоточие, используемое некоторыми операционными системами для обозначения того, что команда открывает диалоговое окно, этот индикатор следует опустить в названии выбора.434435#### `mimetype`436437Название MIME-типа или его компонента (основной или вспомогательной части, взятой отдельно).438439#### `newsgroup`440441Название группы новостей Usenet.442443#### `option`444445Параметр командной строки для исполняемой программы. Начальный дефис (или дефисы) должен быть указан.446447#### `program`448449Название исполняемой программы. Оно может отличаться от имени файла исполняемого файла на некоторых платформах. В частности, расширение450451`.exe`452453(или другое) следует опускать для программ Windows.454455#### `regexp`456457Регулярное выражение. Кавычки не следует включать.458459#### `samp`460461Фрагмент буквального текста, например кода. Внутри содержимого можно использовать фигурные скобки для обозначения «переменной» части, как в `:file:`.462463Если не требуется указание «переменной» части, используйте стандартную разметку `` ``code`` ``.464465#### `var`466467Имя переменной или параметра Python или C.468469Следующие роли создают внешние ссылки:470471#### `pep`472473Ссылка на предложение по улучшению Python (PEP). Она создаёт соответствующие элементы индекса. Генерируется текст «PEP474475*number*476477»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного PEP.478479#### `rfc`480481Ссылка на RFC (Internet Request for Comments). Она создаёт соответствующие элементы индекса. Генерируется текст «RFC482483*number*484485»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного RFC.486487Обратите внимание, что не существует специальных ролей для включения гиперссылок, поскольку для этой цели можно использовать стандартную разметку reST.488489## Разметка перекрёстных ссылок490491Для поддержки перекрёстных ссылок на произвольные разделы документации, стандартные метки reST используются несколько нестандартно: каждая метка должна предшествовать заголовку раздела, и каждое имя метки должно быть уникальным во всём исходном тексте документации.492493Затем можно ссылаться на эти разделы с помощью роли `` :ref:`label-name` ``.494495Пример:496497```rest498.. _my-reference-label:499500Section to cross-reference501--------------------------502503This is the text of the section.504505It refers to the section itself, see :ref:`my-reference-label`.506```507508Вызов `:ref:` заменяется заголовком раздела.509510## Разметка на уровне абзацев511512Эти директивы создают короткие абзацы и могут использоваться внутри информационных блоков, а также в обычном тексте:513514#### `note`515516Особо важная информация об API, о которой пользователь должен знать при использовании той части API, к которой относится примечание. Содержание директивы должно быть написано полными предложениями и включать все соответствующие знаки препинания.517518Пример:519520```rest521.. note::522523 This function is not suitable for sending spam e-mails.524```525526#### `warning`527528Важная информация об API, которую пользователь должен обязательно знать при использовании той части API, к которой относится предупреждение. Содержимое директивы должно быть написано полными предложениями с соответствующими знаками препинания. Это отличается от529530`note`531532тем, что для информации, касающейся безопасности, рекомендуется использовать533534`note`535536.537538#### `versionadded`539540Эта директива указывает версию Python, в которой описанная возможность была добавлена в библиотеку или C API. Если это относится ко всему модулю, её следует размещать в начале раздела модуля, до любого текста.541542Первый аргумент обязателен и указывает версию; можно добавить второй аргумент, содержащий *краткое* описание изменения.543544Пример:545546```rest547.. versionadded:: 3.1548 The *spam* parameter.549```550551Обратите внимание, что между заголовком директивы и пояснением не должно быть пустых строк; это сделано для визуальной непрерывности блоков в разметке.552553#### `versionchanged`554555Аналогично556557`добавлено в версии`558559, но описывает, когда и что именно изменилось в указанной возможности (новые параметры, изменившиеся побочные эффекты и т.д.).560561---562563#### `seealso`564565Во многих разделах есть списки ссылок на документацию модулей или внешние документы. Эти списки создаются с помощью директивы `смотри также`.566567Директива `смотри также` обычно размещается в разделе перед любыми подразделами. В HTML-выводе она отображается в рамке, отдельно от основного потока текста.568569Содержимое директивы `смотри также` должно быть списком определений reST. Пример:570571```rest572.. seealso::573574 Module :mod:`zipfile`575 Documentation of the :mod:`zipfile` standard module.576577 `GNU tar manual, Basic Tar Format <http://link>`_578 Documentation for tar archive files, including GNU tar extensions.579```580581#### `rubric`582583Эта директива создаёт заголовок абзаца, который не используется для создания узла оглавления. В настоящее время она применяется для заголовка «Сноски».584585#### `centered`586587Эта директива создаёт центрированный полужирный абзац. Используйте её следующим образом:588589```rest590.. centered::591592 Paragraph contents.593```594595## Разметка оглавления596597Поскольку в reST нет средств для взаимосвязи нескольких документов или разделения документов на несколько выходных файлов, Sphinx использует специальную директиву для добавления связей между отдельными файлами, из которых состоит документация, а также для оглавлений. Директива `toctree` является центральным элементом.598599#### `toctree`600601Эта директива вставляет «дерево оглавления» в текущее место, используя отдельные оглавления (включая «поддеревья оглавления») файлов, указанных в теле директивы. Можно указать числовой параметр `maxdepth`, чтобы задать глубину дерева; по умолчанию включаются все уровни.602603Рассмотрим этот пример (взятый из указателя библиотечных ссылок):604605```rest606.. toctree::607 :maxdepth: 2608609 intro.rst610 strings.rst611 datatypes.rst612 numeric.rst613 (many more files listed here)614```615616Это делает две вещи:617618- Вставляются оглавления всех этих файлов с максимальной глубиной два, то есть один вложенный заголовок. Директивы `toctree` в этих файлах также учитываются.619- Sphinx знает относительный порядок файлов `intro.rst`, `strings.rst` и так далее, а также то, что они являются дочерними по отношению к показанному файлу – индексу библиотеки. На основе этой информации он генерирует ссылки «следующая глава», «предыдущая глава» и «родительская глава».620621В конечном итоге все файлы, включённые в процесс сборки, должны присутствовать в одной директиве `toctree`; Sphinx выдаст предупреждение, если обнаружит файл, который не включён, поскольку это означает, что данный файл будет недоступен через стандартную навигацию.622623Специальный файл `contents.rst` в корне исходного каталога является «корнем» иерархии дерева оглавления; на его основе генерируется страница «Содержание».624625## Разметка для создания индексов626627Sphinx автоматически создаёт записи индекса для всех информационных единиц (таких как функции, классы или атрибуты), как уже обсуждалось.628629Однако есть и явная директива, которая делает индекс более полным и позволяет добавлять записи индекса в документы, где информация не сосредоточена в информационных единицах, – например, в справочнике по языку.630631Директива называется `index` и содержит одну или несколько записей индекса. Каждая запись состоит из типа и значения, разделённых двоеточием.632633Например:634635```rest636.. index::637 single: execution; context638 module: __main__639 module: sys640 triple: module; search; path641```642643Эта директива содержит пять записей, которые будут преобразованы в записи генерируемого индекса, ссылающиеся на точное местоположение указания индекса (или, в случае офлайн-носителей, на соответствующий номер страницы).644645Возможные типы записей:646647**single**648649Создаёт одну запись индекса. Может быть преобразована в подзапись: текст подзаписи отделяется точкой с запятой (это же обозначение используется ниже для описания создаваемых записей).650651**pair**652653`pair: loop; statement`654655– это сокращение, которое создаёт две записи индекса, а именно656657`loop; statement`658659и660661`statement; loop`662663.664665**тройной**666667Аналогично,668669`triple: module; search; path`670671– это сокращение, которое создаёт три записи индекса:672673`module; search path`674675,676677`search; path, module`678679и680681`path; module search`682683.684685**модуль, ключевое слово, оператор, объект, исключение, инструкция, встроенная функция**686687Все они создают по две записи индекса. Например,688689`module: hashlib`690691создаёт записи692693`module; hashlib`694695и696697`hashlib; module`698699.700701Для директив индекса, содержащих только записи типа «single», существует сокращённая запись:702703```rest704.. index:: BNF, grammar, syntax, notation705```706707Это создаёт четыре записи индекса.708709## Отображения правил грамматики710711Для отображения продукций формальной грамматики доступна специальная разметка. Она проста и не пытается моделировать все аспекты БНФ (или любых производных форм), но предоставляет достаточно возможностей, чтобы контекстно-свободные грамматики отображались так, что использование символа показывает гиперссылку на его определение. Существует следующая директива:712713#### `productionlist`714715Эта директива используется для обрамления группы продукций. Каждая продукция задаётся на одной строке и состоит из имени, отделённого двоеточием от следующего за ним определения. Если определение занимает несколько строк, каждая строка продолжения должна начинаться с двоеточия, расположенного в том же столбце, что и в первой строке.716717Пустые строки не допускаются в аргументах директивы `productionlist`.718719Определение может содержать имена токенов, которые помечены как интерпретируемый текст (например, `` unaryneg ::= "-" `integer` ``) – это создаёт перекрёстные ссылки на продукции этих токенов.720721Обратите внимание, что в продукции не выполняется дальнейший разбор reST, поэтому не нужно экранировать символы `*` или `|`.722723Ниже приведён пример из Справочного руководства по Python:724725```rest726.. productionlist::727 try_stmt: try1_stmt | try2_stmt728 try1_stmt: "try" ":" `suite`729 : ("except" [`expression` ["," `target`]] ":" `suite`)+730 : ["else" ":" `suite`]731 : ["finally" ":" `suite`]732 try2_stmt: "try" ":" `suite`733 : "finally" ":" `suite`734```735736## Подстановки737738Система документации предоставляет три подстановки, определённые по умолчанию. Они задаются в файле конфигурации сборки `conf.py`.739740#### `|release|`741742Заменяется на версию Python, к которой относится документация. Это полная строка версии, включающая теги альфа/бета/кандидата на выпуск, например743744`2.5.2b3`745746.747748#### `|version|`749750Заменяется на номер версии Python, к которой относится документация. Он состоит только из major и minor частей версии, например751752`2.5`753754, даже для версии 2.5.1.755756#### `|today|`757758Заменяется либо на сегодняшнюю дату, либо на дату, указанную в файле конфигурации сборки. Обычно имеет формат759760`April 14, 2007`761762.763764Сноски765766| [\[1\]](https://python-all.ru/3.0/documenting/markup.html#id1) | Существует стандартная директива `.. include`, но она вызывает ошибки, если файл не найден. Эта директива выдает только предупреждение. |767| --- | --- |768