markup.md
1> **Источник:** https://python-all.ru/2.6/documenting/markup.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 4. Дополнительные конструкции разметки89Sphinx добавляет множество новых директив и интерпретируемых текстовых ролей к стандартной разметке reST. В этом разделе содержится справочная информация об этих средствах. Документация по «стандартным» конструкциям reST здесь не приводится, хотя они используются в документации Python.1011> **Примечание**12>13> Это лишь обзор расширенных возможностей разметки Sphinx; полное описание можно найти в [его собственной документации](https://python-all.ru/2.6/documenting/markup.html).1415## 4.1. Разметка метаинформации1617#### `sectionauthor`1819Определяет автора текущего раздела. Аргумент должен содержать имя автора (так, чтобы его можно было использовать для отображения, хотя сейчас это не используется) и адрес электронной почты. Доменная часть адреса должна быть в нижнем регистре. Пример:2021```rest22.. sectionauthor:: Guido van Rossum <guido@python.org>23```2425В настоящее время эта разметка никак не отображается в выводе, но помогает отслеживать вклад авторов.2627## 4.2. Разметка для модулей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## 4.3. Информационные единицы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/2.6/c-api/structures.html#PyObject_HEAD)113114и115116[`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/2.6/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/2.6/glossary.html#term-bytecode)177178Python.179180#### `cmdoption`181182Описывает опцию или переключатель командной строки Python. Имена аргументов опций следует заключать в угловые скобки. Пример: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## 4.4. Примеры кода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/2.6/documenting/markup.html#id2) Например, чтобы включить исходный файл Python `example.py`, используйте:238239```rest240.. literalinclude:: example.py241```242243Имя файла задаётся относительно пути текущего файла. Специфические для документации файлы включений следует помещать в подкаталог `Doc/includes`.244245## 4.5. Встроенная разметка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/2.6/library/codecs.html#module-codecs), `` :func:`open` `` всегда ссылается на встроенную функцию, в то время как `` :func:`.open` `` ссылается на [`codecs.open()`](https://python-all.ru/2.6/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/2.6/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Параметр командной строки Python. Начальный дефис (или дефисы) должны быть включены. Если существует соответствующая директива446447`cmdoption`448449, ссылка ведёт на неё. Для параметров других программ или сценариев используйте простую разметку450451`` ``code`` ``452453.454455#### `program`456457Название исполняемой программы. Оно может отличаться от имени файла исполняемого файла на некоторых платформах. В частности, расширение458459`.exe`460461(или другое) следует опускать для программ Windows.462463#### `regexp`464465Регулярное выражение. Кавычки не следует включать.466467#### `samp`468469Фрагмент буквального текста, например кода. Внутри содержимого можно использовать фигурные скобки для обозначения «переменной» части, как в `:file:`.470471Если не требуется указание «переменной» части, используйте стандартную разметку `` ``code`` ``.472473#### `var`474475Имя переменной или параметра Python или C.476477Следующие роли создают внешние ссылки:478479#### `pep`480481Ссылка на предложение по улучшению Python (PEP). Она создаёт соответствующие элементы индекса. Генерируется текст «PEP482483*number*484485»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного PEP.486487#### `rfc`488489Ссылка на RFC (Internet Request for Comments). Она создаёт соответствующие элементы индекса. Генерируется текст «RFC490491*number*492493»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного RFC.494495Обратите внимание, что не существует специальных ролей для включения гиперссылок, поскольку для этой цели можно использовать стандартную разметку reST.496497## 4.6. Разметка перекрёстных ссылок498499Для поддержки перекрёстных ссылок на произвольные разделы документации, стандартные метки reST используются несколько нестандартно: каждая метка должна предшествовать заголовку раздела, и каждое имя метки должно быть уникальным во всём исходном тексте документации.500501Затем можно ссылаться на эти разделы с помощью роли `` :ref:`label-name` ``.502503Пример:504505```rest506.. _my-reference-label:507508Section to cross-reference509--------------------------510511This is the text of the section.512513It refers to the section itself, see :ref:`my-reference-label`.514```515516Вызов `:ref:` заменяется заголовком раздела.517518## 4.7. Разметка уровня абзаца519520Эти директивы создают короткие абзацы и могут использоваться внутри информационных блоков, а также в обычном тексте:521522#### `note`523524Особо важная информация об API, о которой пользователь должен знать при использовании той части API, к которой относится примечание. Содержание директивы должно быть написано полными предложениями и включать все соответствующие знаки препинания.525526Пример:527528```rest529.. note::530531 This function is not suitable for sending spam e-mails.532```533534#### `warning`535536Важная информация об API, о которой пользователь должен знать при использовании той части API, к которой относится предупреждение. Содержание директивы должно быть написано полными предложениями и включать все соответствующие знаки препинания. Чтобы не отпугивать пользователей от страниц, заполненных предупреждениями, эту директиву следует выбирать вместо537538`примечание`539540только для информации, касающейся возможности сбоев, потери данных или последствий для безопасности.541542#### `versionadded`543544Эта директива указывает версию Python, в которой описанная возможность была добавлена в библиотеку или C API. Если это относится ко всему модулю, её следует размещать в начале раздела модуля, до любого текста.545546Первый аргумент обязателен и указывает версию; можно добавить второй аргумент, содержащий *краткое* описание изменения.547548Пример:549550```rest551.. versionadded:: 2.5552 The *spam* parameter.553```554555Обратите внимание, что между заголовком директивы и пояснением не должно быть пустых строк; это сделано для визуальной непрерывности блоков в разметке.556557#### `versionchanged`558559Аналогично560561`добавлено в версии`562563, но описывает, когда и что именно изменилось в указанной возможности (новые параметры, изменившиеся побочные эффекты и т.д.).564565---566567#### `impl-detail`568569Эта директива используется для пометки информации, специфичной для CPython. Используйте её либо с блочным содержимым, либо с одним предложением в качестве аргумента, то есть:570571```rest572.. impl-detail::573574 This describes some implementation detail.575576 More explanation.577```578579или580581```rest582.. impl-detail:: This shortly mentions an implementation detail.583```584585«**Детали реализации CPython:**» автоматически добавляется перед содержимым.586587#### `seealso`588589Во многих разделах есть списки ссылок на документацию модулей или внешние документы. Эти списки создаются с помощью директивы `смотри также`.590591Директива `смотри также` обычно размещается в разделе перед любыми подразделами. В HTML-выводе она отображается в рамке, отдельно от основного потока текста.592593Содержимое директивы `смотри также` должно быть списком определений reST. Пример:594595```rest596.. seealso::597598 Module :mod:`zipfile`599 Documentation of the :mod:`zipfile` standard module.600601 `GNU tar manual, Basic Tar Format <http://link>`_602 Documentation for tar archive files, including GNU tar extensions.603```604605#### `rubric`606607Эта директива создаёт заголовок абзаца, который не используется для создания узла оглавления. В настоящее время она применяется для заголовка «Сноски».608609#### `centered`610611Эта директива создаёт центрированный полужирный абзац. Используйте её следующим образом:612613```rest614.. centered::615616 Paragraph contents.617```618619## 4.8. Разметка оглавления620621Поскольку в reST нет средств для взаимосвязи нескольких документов или разделения документов на несколько выходных файлов, Sphinx использует специальную директиву для добавления связей между отдельными файлами, из которых состоит документация, а также для оглавлений. Директива `toctree` является центральным элементом.622623#### `toctree`624625Эта директива вставляет «дерево оглавления» в текущее место, используя отдельные оглавления (включая «поддеревья оглавления») файлов, указанных в теле директивы. Можно указать числовой параметр `maxdepth`, чтобы задать глубину дерева; по умолчанию включаются все уровни.626627Рассмотрим этот пример (взятый из указателя библиотечных ссылок):628629```rest630.. toctree::631 :maxdepth: 2632633 intro.rst634 strings.rst635 datatypes.rst636 numeric.rst637 (many more files listed here)638```639640Это делает две вещи:641642- Вставляются оглавления всех этих файлов с максимальной глубиной два, то есть один вложенный заголовок. Директивы `toctree` в этих файлах также учитываются.643- Sphinx знает относительный порядок файлов `intro.rst`, `strings.rst` и так далее, а также то, что они являются дочерними по отношению к показанному файлу – индексу библиотеки. На основе этой информации он генерирует ссылки «следующая глава», «предыдущая глава» и «родительская глава».644645В конечном итоге все файлы, включённые в процесс сборки, должны присутствовать в одной директиве `toctree`; Sphinx выдаст предупреждение, если обнаружит файл, который не включён, поскольку это означает, что данный файл будет недоступен через стандартную навигацию.646647Специальный файл `contents.rst` в корне исходного каталога является «корнем» иерархии дерева оглавления; на его основе генерируется страница «Содержание».648649## 4.9. Разметка для генерации индекса650651Sphinx автоматически создаёт записи индекса для всех информационных единиц (таких как функции, классы или атрибуты), как уже обсуждалось.652653Однако есть и явная директива, которая делает индекс более полным и позволяет добавлять записи индекса в документы, где информация не сосредоточена в информационных единицах, – например, в справочнике по языку.654655Директива называется `index` и содержит одну или несколько записей индекса. Каждая запись состоит из типа и значения, разделённых двоеточием.656657Например:658659```rest660.. index::661 single: execution; context662 module: __main__663 module: sys664 triple: module; search; path665```666667Эта директива содержит пять записей, которые будут преобразованы в записи генерируемого индекса, ссылающиеся на точное местоположение указания индекса (или, в случае офлайн-носителей, на соответствующий номер страницы).668669Возможные типы записей:670671**single**672673Создаёт одну запись индекса. Может быть преобразована в подзапись: текст подзаписи отделяется точкой с запятой (это же обозначение используется ниже для описания создаваемых записей).674675**pair**676677`pair: loop; statement`678679– это сокращение, которое создаёт две записи индекса, а именно680681`loop; statement`682683и684685`statement; loop`686687.688689**тройной**690691Аналогично,692693`triple: module; search; path`694695– это сокращение, которое создаёт три записи индекса:696697`module; search path`698699,700701`search; path, module`702703и704705`path; module search`706707.708709**модуль, ключевое слово, оператор, объект, исключение, инструкция, встроенная функция**710711Все они создают по две записи индекса. Например,712713`module: hashlib`714715создаёт записи716717`module; hashlib`718719и720721`hashlib; module`722723.724725Для директив индекса, содержащих только записи типа «single», существует сокращённая запись:726727```rest728.. index:: BNF, grammar, syntax, notation729```730731Это создаёт четыре записи индекса.732733## 4.10. Отображение грамматических продукций734735Для отображения продукций формальной грамматики доступна специальная разметка. Она проста и не пытается моделировать все аспекты БНФ (или любых производных форм), но предоставляет достаточно возможностей, чтобы контекстно-свободные грамматики отображались так, что использование символа показывает гиперссылку на его определение. Существует следующая директива:736737#### `productionlist`738739Эта директива используется для обрамления группы продукций. Каждая продукция задаётся на одной строке и состоит из имени, отделённого двоеточием от следующего за ним определения. Если определение занимает несколько строк, каждая строка продолжения должна начинаться с двоеточия, расположенного в том же столбце, что и в первой строке.740741Пустые строки не допускаются в аргументах директивы `productionlist`.742743Определение может содержать имена токенов, которые помечены как интерпретируемый текст (например, `` unaryneg ::= "-" `integer` ``) – это создаёт перекрёстные ссылки на продукции этих токенов.744745Обратите внимание, что в продукции не выполняется дальнейший разбор reST, поэтому не нужно экранировать символы `*` или `|`.746747Ниже приведён пример из Справочного руководства по Python:748749```rest750.. productionlist::751 try_stmt: try1_stmt | try2_stmt752 try1_stmt: "try" ":" `suite`753 : ("except" [`expression` ["," `target`]] ":" `suite`)+754 : ["else" ":" `suite`]755 : ["finally" ":" `suite`]756 try2_stmt: "try" ":" `suite`757 : "finally" ":" `suite`758```759760## 4.11. Подстановки761762Система документации предоставляет три подстановки, определённые по умолчанию. Они задаются в файле конфигурации сборки `conf.py`.763764#### `|release|`765766Заменяется на версию Python, к которой относится документация. Это полная строка версии, включающая теги альфа/бета/кандидата на выпуск, например767768`2.5.2b3`769770.771772#### `|version|`773774Заменяется на номер версии Python, к которой относится документация. Он состоит только из major и minor частей версии, например775776`2.5`777778, даже для версии 2.5.1.779780#### `|today|`781782Заменяется либо на сегодняшнюю дату, либо на дату, указанную в файле конфигурации сборки. Обычно имеет формат783784`April 14, 2007`785786.787788Сноски789790| [\[1\]](https://python-all.ru/2.6/documenting/markup.html#id1) | Существует стандартная директива `.. include`, но она вызывает ошибки, если файл не найден. Эта директива выдает только предупреждение. |791| --- | --- |792