markup.md
1> **Источник:** https://python-all.ru/3.1/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/3.1/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/3.1/c-api/structures.html#PyObject_HEAD)113114и115116[`Py_BEGIN_ALLOW_THREADS`](https://python-all.ru/3.1/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:: repeat([repeat=3[, number=1000000]])146```147148Методы объектов не документируются с помощью этой директивы. Связанные методы объектов, помещённые в пространство имён модуля как часть его публичного интерфейса, документируются с её помощью, поскольку в большинстве случаев они эквивалентны обычным функциям.149150Описание должно включать информацию о требуемых параметрах и способах их использования (в особенности, изменяются ли передаваемые изменяемые объекты), побочных эффектах и возможных исключениях. Может быть приведён небольшой пример.151152#### `class`153154Описывает класс. Сигнатура может включать скобки с параметрами, которые будут отображаться как аргументы конструктора.155156#### `attribute`157158Описывает атрибут данных объекта. Описание должно включать информацию об ожидаемом типе данных и о том, можно ли его изменять напрямую. Эту директиву следует вкладывать в директиву класса, как в этом примере:159160```rest161.. class:: Spam162163 Description of the class.164165 .. data:: ham166167 Description of the attribute.168```169170Также есть возможность документировать атрибут вне директивы класса, например, если документация для разных атрибутов и методов разбита на несколько разделов. В этом случае имя класса следует указывать явно:171172```rest173.. data:: Spam.eggs174```175176#### `method`177178Описывает метод объекта. Параметры не должны включать179180`self`181182параметр. Описание должно содержать информацию, аналогичную описанной для183184`function`185186. Эту директиву следует вкладывать в директиву класса, как в примере выше.187188#### `opcode`189190Описывает инструкцию191192[*байт-кода*](https://python-all.ru/3.1/glossary.html#term-bytecode)193194Python.195196#### `cmdoption`197198Описывает опцию или переключатель командной строки Python. Имена аргументов опций следует заключать в угловые скобки. Пример:199200```rest201.. cmdoption:: -m <module>202203 Run a module as a script.204```205206#### `envvar`207208Описывает переменную окружения, которую Python использует или определяет.209210Также существует обобщённая версия этих директив:211212#### `describe`213214Эта директива создаёт такое же форматирование, как и описанные выше конкретные, но не создаёт записи в индексе или цели для перекрёстных ссылок. Она используется, например, для описания директив в этом документе. Пример:215216```rest217.. describe:: opcode218219 Describes a Python bytecode instruction.220```221222## 4.4. Примеры кода223224Примеры исходного кода Python или интерактивных сеансов представляются с помощью стандартных буквальных блоков reST. Они начинаются с `::` в конце предыдущего абзаца и выделяются отступом.225226Для представления интерактивного сеанса необходимо включать приглашения и вывод вместе с кодом Python. После последней строки ввода или вывода не должно быть «лишнего» основного приглашения; вот пример того, как *не* следует делать:227228```rest229>>> 1 + 12302231>>>232```233234Подсветка синтаксиса обрабатывается интеллектуально:235236- Для каждого исходного файла существует «язык подсветки». По умолчанию, это `'python'`, поскольку большинство файлов должно подсвечивать фрагменты Python.237- В режиме подсветки Python интерактивные сеансы распознаются автоматически и подсвечиваются соответствующим образом.238- Язык подсветки можно изменить с помощью директивы `highlightlang`, используемой следующим образом:239240 ```rest241 .. highlightlang:: c242 ```243244 Этот язык используется до тех пор, пока не будет встречена следующая директива `highlightlang`.245- Обычно используемые значения для языка подсветки:246247 - `python` (по умолчанию)248 - `c`249 - `rest`250 - `none` (без подсветки)251- Если подсветка с текущим языком не работает, блок не подсвечивается никаким образом.252253Длинные примеры буквального текста можно включать, сохранив пример в отдельном файле, содержащем только обычный текст. Файл можно подключить с помощью директивы `literalinclude`. [\[1\]](https://python-all.ru/3.1/documenting/markup.html#id2) Например, чтобы включить исходный файл Python `example.py`, используйте:254255```rest256.. literalinclude:: example.py257```258259Имя файла задаётся относительно пути текущего файла. Специфические для документации файлы включений следует помещать в подкаталог `Doc/includes`.260261## 4.5. Встроенная разметка262263Как уже говорилось, Sphinx использует интерпретируемые текстовые роли для вставки семантической разметки в документы.264265Имена локальных переменных, таких как аргументы функций/методов, являются исключением; их следует просто помечать с помощью `*var*`.266267Для всех остальных ролей нужно писать `` :rolename:`content` ``.268269Существуют некоторые дополнительные средства, которые делают роли перекрёстных ссылок более гибкими:270271- Можно указать явный заголовок и цель ссылки, как в прямых гиперссылках reST: `` :role:`title <target>` `` будет ссылаться на *target*, но текст ссылки будет *title*.272- Если перед содержимым указать `!`, ссылка/гиперссылка не будет создана.273- Для ролей объектов Python, если перед содержимым поставить `~`, текст ссылки будет содержать только последний компонент цели. Например, `` :meth:`~Queue.Queue.get` `` будет ссылаться на `Queue.Queue.get`, но отображать в качестве текста ссылки только `get`.274275 В HTML-выводе атрибут `title` ссылки (который, например, отображается как всплывающая подсказка при наведении мыши) всегда будет содержать полное имя цели.276277Следующие роли ссылаются на объекты в модулях и, возможно, будут гиперссылками, если будет найден соответствующий идентификатор:278279#### `mod`280281Имя модуля; может использоваться точечное имя. Это также следует использовать для имён пакетов.282283#### `func`284285Имя функции Python; могут использоваться точечные имена. Текст роли не должен включать завершающие круглые скобки для улучшения читаемости. Скобки отбрасываются при поиске идентификаторов.286287#### `data`288289Имя переменной или константы уровня модуля.290291#### `const`292293Имя «определённой» константы. Это может быть294295`#define`296297языка C или переменная Python, которая не предназначена для изменения.298299#### `class`300301Имя класса; может использоваться точечное имя.302303#### `meth`304305Имя метода объекта. Текст роли должен включать имя типа и имя метода. Может использоваться точечное имя.306307#### `attr`308309Имя атрибута данных объекта.310311#### `exc`312313Имя исключения. Может использоваться точечное имя.314315Имя, заключённое в эту разметку, может включать имя модуля и/или имя класса. Например, `` :func:`filter` `` может ссылаться на функцию с именем `filter` в текущем модуле или на встроенную функцию с таким именем. В отличие от этого, `` :func:`foo.filter` `` явно ссылается на функцию `filter` в модуле `foo`.316317Обычно имена в этих ролях сначала ищутся без дополнительных уточнений, затем с добавлением имени текущего модуля, затем с добавлением имени текущего модуля и класса (если он есть). Если перед именем поставить точку, порядок меняется на обратный. Например, в документации модуля [`codecs`](https://python-all.ru/3.1/library/codecs.html#module-codecs), `` :func:`open` `` всегда ссылается на встроенную функцию, в то время как `` :func:`.open` `` ссылается на [`codecs.open()`](https://python-all.ru/3.1/library/codecs.html#codecs.open).318319Похожая эвристика используется для определения, является ли имя атрибутом текущего документируемого класса.320321Следующие роли создают перекрёстные ссылки на конструкции языка C, если они определены в документации API:322323#### `cdata`324325Имя переменной на языке C.326327#### `cfunc`328329Имя функции на языке C. Должно включать завершающие круглые скобки.330331#### `cmacro`332333Имя «простой» C-макроса, как определено выше.334335#### `ctype`336337Имя типа на языке C.338339Следующая роль, возможно, создает перекрестную ссылку, но не ссылается на объекты:340341#### `token`342343Имя грамматического токена (используется в справочном руководстве для создания ссылок между отображениями порождающих правил).344345Следующая роль создает перекрестную ссылку на термин в глоссарии:346347#### `term`348349Ссылка на термин в глоссарии. Глоссарий создается с помощью директивы `glossary`, содержащей список определений с терминами и определениями. Он не обязательно должен находиться в том же файле, что и разметка `term` на самом деле, по умолчанию документация Python имеет один глобальный глоссарий в файле `glossary.rst`.350351Если используется термин, не объясненный в глоссарии, при сборке будет выдано предупреждение.352353---354355Следующие роли не делают ничего особенного, кроме форматирования текста в другом стиле:356357#### `command`358359Имя команды уровня ОС, например360361`rm`362363.364365#### `dfn`366367Отмечает определяющее вхождение термина в тексте. (Записи в указателе не создаются.)368369#### `envvar`370371Переменная окружения. Записи в указателе создаются.372373#### `file`374375Имя файла или каталога. В содержимом можно использовать фигурные скобки для обозначения «переменной» части, например:376377```rest378... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...379```380381В собранной документации `x` будет отображаться иначе, чтобы указать, что он должен быть заменен на минорную версию Python.382383#### `guilabel`384385Метки, представленные как часть интерактивного пользовательского интерфейса, должны быть отмечены с помощью386387`guilabel`388389. Это включает метки из текстовых интерфейсов, таких как созданных с использованием390391[`curses`](https://python-all.ru/3.1/library/curses.html#module-curses)392393или других текстовых библиотек. Любая метка, используемая в интерфейсе, должна быть отмечена этой ролью, включая надписи на кнопках, заголовки окон, имена полей, названия меню и пунктов меню и даже значения в списках выбора.394395#### `kbd`396397Отмечает последовательность нажатий клавиш. Форма последовательности клавиш может зависеть от соглашений, специфичных для платформы или приложения. Если соответствующих соглашений нет, названия клавиш-модификаторов следует писать полностью, чтобы улучшить доступность для новых пользователей и неносителей языка. Например, последовательность клавиш398399*xemacs*400401может быть отмечена как402403`` :kbd:`C-x C-f` ``404405, но без ссылки на конкретное приложение или платформу та же последовательность должна быть отмечена как406407`` :kbd:`Control-x Control-f` ``408409.410411#### `keyword`412413Имя ключевого слова в Python.414415#### `mailheader`416417Имя почтового заголовка в стиле RFC 822. Эта разметка не подразумевает, что заголовок используется в сообщении электронной почты, но может использоваться для ссылки на любой заголовок того же «стиля». Она также используется для заголовков, определенных различными спецификациями MIME. Имя заголовка должно вводиться так же, как оно обычно встречается на практике, с предпочтением соглашений верблюжьего регистра, если существует более одного распространенного варианта. Например:418419`` :mailheader:`Content-Type` ``420421.422423#### `makevar`424425Имя переменной426427**make**428429.430431#### `manpage`432433Ссылка на страницу руководства Unix, включая раздел, например434435`` :manpage:`ls(1)` ``436437.438439#### `menuselection`440441Пункты меню следует отмечать с помощью роли `menuselection`. Она используется для разметки полной последовательности выбора пунктов меню, включая выбор подменю и выбор конкретной операции, или любой подпоследовательности такой последовательности. Названия отдельных пунктов должны разделяться `-->`.442443Например, чтобы отметить выбор «Пуск \> Программы», используйте эту разметку:444445```rest446:menuselection:`Start --> Programs`447```448449При включении выбора, который содержит завершающий индикатор, например многоточие, используемое некоторыми операционными системами для обозначения того, что команда открывает диалоговое окно, этот индикатор следует опустить в названии выбора.450451#### `mimetype`452453Название MIME-типа или его компонента (основной или вспомогательной части, взятой отдельно).454455#### `newsgroup`456457Название группы новостей Usenet.458459#### `option`460461Параметр командной строки Python. Начальный дефис (или дефисы) должны быть включены. Если существует соответствующая директива462463`cmdoption`464465, ссылка ведёт на неё. Для параметров других программ или сценариев используйте простую разметку466467`` ``code`` ``468469.470471#### `program`472473Название исполняемой программы. Оно может отличаться от имени файла исполняемого файла на некоторых платформах. В частности, расширение474475`.exe`476477(или другое) следует опускать для программ Windows.478479#### `regexp`480481Регулярное выражение. Кавычки не следует включать.482483#### `samp`484485Фрагмент буквального текста, например кода. Внутри содержимого можно использовать фигурные скобки для обозначения «переменной» части, как в `:file:`.486487Если не требуется указание «переменной» части, используйте стандартную разметку `` ``code`` ``.488489#### `var`490491Имя переменной или параметра Python или C.492493Следующие роли создают внешние ссылки:494495#### `pep`496497Ссылка на предложение по улучшению Python (PEP). Она создаёт соответствующие элементы индекса. Генерируется текст «PEP498499*number*500501»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного PEP.502503#### `rfc`504505Ссылка на RFC (Internet Request for Comments). Она создаёт соответствующие элементы индекса. Генерируется текст «RFC506507*number*508509»; в HTML-выводе этот текст является гиперссылкой на онлайн-копию указанного RFC.510511Обратите внимание, что не существует специальных ролей для включения гиперссылок, поскольку для этой цели можно использовать стандартную разметку reST.512513## 4.6. Разметка перекрёстных ссылок514515Для поддержки перекрёстных ссылок на произвольные разделы документации, стандартные метки reST используются несколько нестандартно: каждая метка должна предшествовать заголовку раздела, и каждое имя метки должно быть уникальным во всём исходном тексте документации.516517Затем можно ссылаться на эти разделы с помощью роли `` :ref:`label-name` ``.518519Пример:520521```rest522.. _my-reference-label:523524Section to cross-reference525--------------------------526527This is the text of the section.528529It refers to the section itself, see :ref:`my-reference-label`.530```531532Вызов `:ref:` заменяется заголовком раздела.533534## 4.7. Разметка уровня абзаца535536Эти директивы создают короткие абзацы и могут использоваться внутри информационных блоков, а также в обычном тексте:537538#### `note`539540Особо важная информация об API, о которой пользователь должен знать при использовании той части API, к которой относится примечание. Содержание директивы должно быть написано полными предложениями и включать все соответствующие знаки препинания.541542Пример:543544```rest545.. note::546547 This function is not suitable for sending spam e-mails.548```549550#### `warning`551552Важная информация об API, о которой пользователь должен знать при использовании той части API, к которой относится предупреждение. Содержание директивы должно быть написано полными предложениями и включать все соответствующие знаки препинания. Чтобы не отпугивать пользователей от страниц, заполненных предупреждениями, эту директиву следует выбирать вместо553554`примечание`555556только для информации, касающейся возможности сбоев, потери данных или последствий для безопасности.557558#### `versionadded`559560Эта директива указывает версию Python, в которой описанная возможность была добавлена в библиотеку или C API. Если это относится ко всему модулю, её следует размещать в начале раздела модуля, до любого текста.561562Первый аргумент обязателен и указывает версию; можно добавить второй аргумент, содержащий *краткое* описание изменения.563564Пример:565566```rest567.. versionadded:: 3.1568 The *spam* parameter.569```570571Обратите внимание, что между заголовком директивы и пояснением не должно быть пустых строк; это сделано для визуальной непрерывности блоков в разметке.572573#### `versionchanged`574575Аналогично576577`добавлено в версии`578579, но описывает, когда и что именно изменилось в указанной возможности (новые параметры, изменившиеся побочные эффекты и т.д.).580581---582583#### `impl-detail`584585Эта директива используется для пометки информации, специфичной для CPython. Используйте её либо с блочным содержимым, либо с одним предложением в качестве аргумента, то есть:586587```rest588.. impl-detail::589590 This describes some implementation detail.591592 More explanation.593```594595или596597```rest598.. impl-detail:: This shortly mentions an implementation detail.599```600601«**Детали реализации CPython:**» автоматически добавляется перед содержимым.602603#### `seealso`604605Во многих разделах есть списки ссылок на документацию модулей или внешние документы. Эти списки создаются с помощью директивы `смотри также`.606607Директива `смотри также` обычно размещается в разделе перед любыми подразделами. В HTML-выводе она отображается в рамке, отдельно от основного потока текста.608609Содержимое директивы `смотри также` должно быть списком определений reST. Пример:610611```rest612.. seealso::613614 Module :mod:`zipfile`615 Documentation of the :mod:`zipfile` standard module.616617 `GNU tar manual, Basic Tar Format <http://link>`_618 Documentation for tar archive files, including GNU tar extensions.619```620621#### `rubric`622623Эта директива создаёт заголовок абзаца, который не используется для создания узла оглавления. В настоящее время она применяется для заголовка «Сноски».624625#### `centered`626627Эта директива создаёт центрированный полужирный абзац. Используйте её следующим образом:628629```rest630.. centered::631632 Paragraph contents.633```634635## 4.8. Разметка оглавления636637Поскольку в reST нет средств для взаимосвязи нескольких документов или разделения документов на несколько выходных файлов, Sphinx использует специальную директиву для добавления связей между отдельными файлами, из которых состоит документация, а также для оглавлений. Директива `toctree` является центральным элементом.638639#### `toctree`640641Эта директива вставляет «дерево оглавления» в текущее место, используя отдельные оглавления (включая «поддеревья оглавления») файлов, указанных в теле директивы. Можно указать числовой параметр `maxdepth`, чтобы задать глубину дерева; по умолчанию включаются все уровни.642643Рассмотрим этот пример (взятый из указателя библиотечных ссылок):644645```rest646.. toctree::647 :maxdepth: 2648649 intro650 strings651 datatypes652 numeric653 (many more files listed here)654```655656Это делает две вещи:657658- Вставляются оглавления всех этих файлов с максимальной глубиной два, то есть один вложенный заголовок. Директивы `toctree` в этих файлах также учитываются.659- Sphinx знает относительный порядок файлов `intro`, `strings` и так далее, а также то, что они являются дочерними по отношению к показанному файлу – указателю библиотеки. На основе этой информации генерируются ссылки «следующая глава», «предыдущая глава» и «родительская глава».660661В конечном итоге все файлы, включённые в процесс сборки, должны присутствовать в одной директиве `toctree`; Sphinx выдаст предупреждение, если обнаружит файл, который не включён, поскольку это означает, что данный файл будет недоступен через стандартную навигацию.662663Специальный файл `contents.rst` в корне исходного каталога является «корнем» иерархии дерева оглавления; на его основе генерируется страница «Содержание».664665## 4.9. Разметка для генерации индекса666667Sphinx автоматически создаёт записи индекса для всех информационных единиц (таких как функции, классы или атрибуты), как уже обсуждалось.668669Однако есть и явная директива, которая делает индекс более полным и позволяет добавлять записи индекса в документы, где информация не сосредоточена в информационных единицах, – например, в справочнике по языку.670671Директива называется `index` и содержит одну или несколько записей индекса. Каждая запись состоит из типа и значения, разделённых двоеточием.672673Например:674675```rest676.. index::677 single: execution; context678 module: __main__679 module: sys680 triple: module; search; path681```682683Эта директива содержит пять записей, которые будут преобразованы в записи генерируемого индекса, ссылающиеся на точное местоположение указания индекса (или, в случае офлайн-носителей, на соответствующий номер страницы).684685Возможные типы записей:686687**single**688689Создаёт одну запись индекса. Может быть преобразована в подзапись: текст подзаписи отделяется точкой с запятой (это же обозначение используется ниже для описания создаваемых записей).690691**pair**692693`pair: loop; statement`694695– это сокращение, которое создаёт две записи индекса, а именно696697`loop; statement`698699и700701`statement; loop`702703.704705**triple**706707Аналогично,708709`triple: module; search; path`710711– это сокращение, которое создаёт три записи индекса:712713`module; search path`714715,716717`search; path, module`718719и720721`path; module search`722723.724725**модуль, ключевое слово, оператор, объект, исключение, инструкция, встроенная функция**726727Все они создают по две записи индекса. Например,728729`module: hashlib`730731создаёт записи732733`module; hashlib`734735и736737`hashlib; module`738739.740741Для директив индекса, содержащих только записи типа «single», существует сокращённая запись:742743```rest744.. index:: BNF, grammar, syntax, notation745```746747Это создаёт четыре записи индекса.748749## 4.10. Отображение грамматических продукций750751Для отображения продукций формальной грамматики доступна специальная разметка. Она проста и не пытается моделировать все аспекты БНФ (или любых производных форм), но предоставляет достаточно возможностей, чтобы контекстно-свободные грамматики отображались так, что использование символа показывает гиперссылку на его определение. Существует следующая директива:752753#### `productionlist`754755Эта директива используется для обрамления группы продукций. Каждая продукция задаётся на одной строке и состоит из имени, отделённого двоеточием от следующего за ним определения. Если определение занимает несколько строк, каждая строка продолжения должна начинаться с двоеточия, расположенного в том же столбце, что и в первой строке.756757Пустые строки не допускаются в аргументах директивы `productionlist`.758759Определение может содержать имена токенов, которые помечены как интерпретируемый текст (например, `` unaryneg ::= "-" `integer` ``) – это создаёт перекрёстные ссылки на продукции этих токенов.760761Обратите внимание, что в продукции не выполняется дальнейший разбор reST, поэтому не нужно экранировать символы `*` или `|`.762763Ниже приведён пример из Справочного руководства по Python:764765```rest766.. productionlist::767 try_stmt: try1_stmt | try2_stmt768 try1_stmt: "try" ":" `suite`769 : ("except" [`expression` ["," `target`]] ":" `suite`)+770 : ["else" ":" `suite`]771 : ["finally" ":" `suite`]772 try2_stmt: "try" ":" `suite`773 : "finally" ":" `suite`774```775776## 4.11. Подстановки777778Система документации предоставляет три подстановки, определённые по умолчанию. Они задаются в файле конфигурации сборки `conf.py`.779780#### `|release|`781782Заменяется на версию Python, к которой относится документация. Это полная строка версии, включающая теги альфа/бета/кандидата на выпуск, например783784`2.5.2b3`785786.787788#### `|version|`789790Заменяется на номер версии Python, к которой относится документация. Он состоит только из major и minor частей версии, например791792`2.5`793794, даже для версии 2.5.1.795796#### `|today|`797798Заменяется либо на сегодняшнюю дату, либо на дату, указанную в файле конфигурации сборки. Обычно имеет формат799800`April 14, 2007`801802.803804Сноски805806| [\[1\]](https://python-all.ru/3.1/documenting/markup.html#id1) | Существует стандартная директива `.. include`, но она вызывает ошибки, если файл не найден. Эта директива выдает только предупреждение. |807| --- | --- |808