Внутристрочная разметка

Sphinx использует интерпретируемые роли текста для вставки семантической разметки в документы. Они описываются как :rolename:`content`.

Note

Роль по умолчанию (`content`) по умолчанию не имеет никакого специального значения. Вы можете использовать её для чего угодно. Используйте значение конфигурации :confval:`default_role` для привязывания этого к известной роли.

Смотрите domains, где описано добавление ролей в домены.

Синтаксис кросс-ссылок

Кросс-ссылки генерируются многими семантически интерпретируемыми текстовыми ролями. Обычно Вам нужно лишь написать :role:`target`, и будет создана ссылка к элементу с именем target типа, обозначенного role. Текст ссылки будет тот же самый, что и target.

Есть некоторые дополнительные возможности, которые позволяют сделать кросс-ссылки более гибкими:

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

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

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

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

Объекты на кросс-ссылки

Следующие роли описаны в соответствующих доменах:

  • Python
  • C
  • C++
  • JavaScript
  • ReST

Произвольное расположение кросс-ссылок

:ref:

Для обеспечения возможности ссылаться на произвольные места в любом документе, используются стандартные метки (labels) reST. Для того, чтобы это работало имена меток должны быть уникальными в пределах всей документации. Есть два способа, которыми Вы можете сослаться на метки:

  • Если Вы расположили метку непосредственно перед заголовком раздела, то Вы можете сослаться на неё при помощи :ref:`label-name`. Например:

    .. _my-reference-label:

Секция, на которую надо сослаться
----------------------------------

Текст секции...............

А вот ссылка на саму секцию :ref:`my-reference-label`.

    Роль :ref: в таком случае создаст ссылку на раздел, а текстом ссылки будет “Секция, на которую надо сослаться”. Это хорошо работает и в слуае, когда метка и ссылка расположены в различных файлах.

    Автоматические метки также работают с фигурами (figures):

    .. _my-figure:

.. figure:: что-либо

   Заголовок фигуры

    В таком случае :ref:`my-figure` вставит ссылку на фигуру с текстом ссылки “Заголовок фигуры”.

    То же самое работает и для таблиц с указанным заголовком, для этого нужно использовать директиву :dudir:`table`.

  • Метки, которые не расположены перед заголовком раздела тем не менее можно использовать для ссылок, но в таком случае Вы должны указать для ссылки заголовок при помощи такого синтаксиса: :ref:`Link title <label-name>`.

Использование ref более предпочтительно, чем стандартные ссылки reStructuredText на раздел (например, `Section title`_), так как первый способ будет работать и в случае изменения заголовка раздела и работает для всех “сборщиков”, поддерживающих кросс-ссылки.

Кросс-ссылки на документы

New in version 0.6.

Кроме всего вышесказанного есть способ напрямую ссылаться на документы:

:doc:

Ссылка на определённый документ; имя документа может быть указано абсолютным или относительным способом. Например, если в документе sketches/index есть ссылка :doc:`parrot`, то она будет ссылаться на sketches/parrot. Если же ссылкой будет :doc:`/people` или :doc:`../people`, то она будет указывать на people.

Если текст ссылки не указан (в отличие от, например: :doc:`Monty Python members </people>`), то в качестве него будет использоваться заголовок документа.

Ссылки на загружаемые файлы

New in version 0.6.

:download:

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

Когда Вы используете эту роль, то ссылаемый файл автоматически помечается для включения в вывод при сборке (очевидно, это актуально только для HTML вывода). Все загружаемые файлы помещаются в подкаталог _downloads выходного каталога; повторяющиеся имена файлов обрабатываются (duplicate filenames are handled).

Пример:

Смотрите :download:`скрит с примером <../example.py>`.

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

Файл example.py будет скопирован в выходной каталог и будет сгенерирована подходящая ссылка.

Кросс-ссылки на другие элементы

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

:envvar:

Переменная окружения. Создаётся индекс. Кроме того, создаётся ссылка на соответствующую директиву envvar, если она существует.

:token:

Имя грамматического токена (grammar token) (используетя для создания ссылок между директивами productionlist).

:keyword:

Имя ключевого слова Python. Создаёт ссылку на ссылающуюся метку с этим имененем, если она существует.

:option:

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

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

:term:

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

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

Другая семантическая разметка

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

:abbr:

Аббревиатура. Если содержимое роли содержит текст в скобках, то он будет рассмотрен особым образом: в HTML он будет показан как всплывающая подсказка, и лишь однажды будет показан в LaTeX.

Пример: :abbr:`LIFO (last-in, first-out)`.

New in version 0.6.

:command:

Имя команды уровня OS, такая как rm.

:dfn:

Помечает определение в тексте. (Элемента индекса при этом не создаётся.)

:file:

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

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

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

:guilabel:

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

Changed in version 1.0: Клавиши быстрого доступа для GUI меток могут быть добавлены при помощи амперсанда; при выводе он будет удалён, а соответствующая буква будет подчёркнута (например: :guilabel:`&Cancel`). Для вставки самого амперсанда удвойте его.

:kbd:

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

:mailheader:

Имя почтового заголовка в стиле RFC 822. Эта разметка не означает, что заголовок используется в почтовом сообщении, но его можно использовать для ссылки на любой заголовок того же самого “стиля”. Он так же используется для заголовков, определяемых различными MIME спецификациями. Имя заголовка должно быть введено так же, как если бы оно использовалось в деле с предпочтительным использованием CamelCase (where there is more than one common usage). Например: :mailheader:`Content-Type`.

:makevar:

Имя переменных команды make.

:manpage:

Ссылка на Unix manual page, включая раздел, то есть :manpage:`ls(1)`.

:menuselection:

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

Например, для отметки выбора “Start > Programs”, используйте следующую разметку:

:menuselection:`Start --> Programs`

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

menuselection так же поддерживает использование амперсанда, как и guilabel.

:mimetype:

Имя MIME типа, или компонента MIME типа (старшей или младшей части по отдельности).

:newsgroup:

Имя Usenet newsgroup.

:program:

Имя исполняемой программы. Может отличаться от имени файла на некоторых платформах. В частности, на Windows может быть опущено расширение .exe (или другое).

:regexp:

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

:samp:

Кусок текста или кода. В содержимом можно использовать фигурные скобки для обозначения “изменяемой” части, как в file. Например, в :samp:`print 1+{variable}`, часть variable будет выделена.

Если Вам не нужно обозначать “изменяемую часть”, тогда используйте станданый ``code``.

Кроме того, есть роль index для создания элементов индекса.

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

:pep:

Ссылка на Python Enhancement Proposal. Создаёт соответствующий элемент индекса. Генерирует текст “PEP number”; в HTML выводе этот текст является гиперссылкой на он-лайн копию данного PEP. Вы можете создать ссылку на определённый раздел при помощи :pep:`number#anchor`.

:rfc:

Ссылка на Internet Request for Comments. Создаёт соответствующий элемент индекса. Генерирует текст “RFC number”; в HTML выводе этот текст является гиперссылкой на он-лайн копию данного RFC. Вы можете создать ссылку на определённый раздел при помощи :rfc:`number#anchor`.

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

Подстановки

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

|release|

Заменяется релизом проекта, который описывается в документации. Это должна быть строка с полной версией, включая теги alpha/beta/release/candidate, например, 2.5.2b3. Задаётся :confval:`release`.

|version|

Заменяется версией проекта, который описывается в документации. Это должна быть строка только с мажорным и минорным номером версии, например, 2.5 даже для версии 2.5.1. Задаётся :confval:`version`.

|today|

Заменяется либо текущей датой (датой, когда прочитывается документ), или датой, заданой в конфигурационном файле. Обычно имеет формат April 14, 2007. Задаётся при помощи :confval:`today_fmt` и :confval:`today`.