.. highlight:: rest .. _inline-markup: Внутристрочная разметка ======================== Sphinx использует интерпретируемые роли текста для вставки семантической разметки в документы. Они описываются как ``:rolename:`content```. .. note:: Роль по умолчанию (```content```) по умолчанию не имеет никакого специального значения. Вы можете использовать её для чего угодно. Используйте значение конфигурации :confval:`default_role` для привязывания этого к известной роли. Смотрите :ref:`domains`, где описано добавление ролей в домены. .. _xref-syntax: Синтаксис кросс-ссылок ~~~~~~~~~~~~~~~~~~~~~~~~ Кросс-ссылки генерируются многими семантически интерпретируемыми текстовыми ролями. Обычно Вам нужно лишь написать ``:role:`target```, и будет создана ссылка к элементу с именем *target* типа, обозначенного *role*. Текст ссылки будет тот же самый, что и *target*. Есть некоторые дополнительные возможности, которые позволяют сделать кросс-ссылки более гибкими: * Вы можете указать явный заголовок отдельно от цели ссылки, аналогично гипессылкам reST: ``:role:`title ``` будет ссылаться на *target*, но текстом ссылки будет *title*. * Если перед содержанием указать ``!``, то ссылки создано не будет. * Если перед содержанием указать ``~``, текстом ссылки будет только последний компонент цели. Например, ``:py:meth:`~Queue.Queue.get``` будет ссылаться на ``Queue.Queue.get`` но в качестве текта будет отображаться только ``get``. В HTML выводе, атрибут ссылки ``title`` (то, что показывается при наведении мышки на ссылку) всегда будет полным именем цели. Объекты на кросс-ссылки ------------------------- Следующие роли описаны в соответствующих доменах: * :ref:`Python ` * :ref:`C ` * :ref:`C++ ` * :ref:`JavaScript ` * :ref:`ReST ` .. _ref-role: Произвольное расположение кросс-ссылок ---------------------------------------- .. rst:role:: 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 ```. Использование :rst:role:`ref` более предпочтительно, чем стандартные ссылки reStructuredText на раздел (например, ```Section title`_``), так как первый способ будет работать и в случае изменения заголовка раздела и работает для всех "сборщиков", поддерживающих кросс-ссылки. Кросс-ссылки на документы --------------------------- .. versionadded:: 0.6 Кроме всего вышесказанного есть способ напрямую ссылаться на документы: .. rst:role:: doc Ссылка на определённый документ; имя документа может быть указано абсолютным или относительным способом. Например, если в документе ``sketches/index`` есть ссылка ``:doc:`parrot```, то она будет ссылаться на ``sketches/parrot``. Если же ссылкой будет ``:doc:`/people``` или ``:doc:`../people```, то она будет указывать на ``people``. Если текст ссылки не указан (в отличие от, например: ``:doc:`Monty Python members ```), то в качестве него будет использоваться заголовок документа. Ссылки на загружаемые файлы ------------------------------ .. versionadded:: 0.6 .. rst:role:: download Эта роль позволяет сослаться на файлы, которые не являются документами reST и которые можно скачать. Когда Вы используете эту роль, то ссылаемый файл автоматически помечается для включения в вывод при сборке (очевидно, это актуально только для HTML вывода). Все загружаемые файлы помещаются в подкаталог ``_downloads`` выходного каталога; повторяющиеся имена файлов обрабатываются (duplicate filenames are handled). Пример:: Смотрите :download:`скрит с примером <../example.py>`. Имя файла указывается обычно относительно файла, содержащего эту директиву; но если он указан в абсолютном виде (начиная с ``/``), то он рассматривается относительно каталога с исходными файлами. Файл ``example.py`` будет скопирован в выходной каталог и будет сгенерирована подходящая ссылка. Кросс-ссылки на другие элементы ----------------------------------------- Следующие роли позволяют создавать кросс-ссылки, но при этом они не ссылаются на конкретные объекты: .. rst:role:: envvar Переменная окружения. Создаётся индекс. Кроме того, создаётся ссылка на соответствующую директиву :rst:dir:`envvar`, если она существует. .. rst:role:: token Имя грамматического токена (grammar token) (используетя для создания ссылок между директивами :rst:dir:`productionlist`). .. rst:role:: keyword Имя ключевого слова Python. Создаёт ссылку на ссылающуюся метку с этим имененем, если она существует. .. rst:role:: option Опция коммандной строки для выполняемой программы. Начальные тире тоже должны быть включены. Создаёт ссылку на директиву :rst:dir:`option`, если она существует. Следующая роль создаёт ссылку на термин в словаре: .. rst:role:: term Ссылка на термин в словаре. Словарь создаётся при помощи директивы ``glossary``, которая содержит список определений. Он не обязан находиться в том же самом файле, что и ``term``; например, документация Python содержит только один файл ``glossary.rst``. Если Вы используете термин, который не имеет объяснения в словаре, то Вы получете предупреждение при сборке. Другая семантическая разметка ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Следующие роли не делают ничего особенного, кроме форматирования текста в определённом стиле: .. rst:role:: abbr Аббревиатура. Если содержимое роли содержит текст в скобках, то он будет рассмотрен особым образом: в HTML он будет показан как всплывающая подсказка, и лишь однажды будет показан в LaTeX. Пример: ``:abbr:`LIFO (last-in, first-out)```. .. versionadded:: 0.6 .. rst:role:: command Имя команды уровня OS, такая как ``rm``. .. rst:role:: dfn Помечает определение в тексте. (Элемента индекса при этом не создаётся.) .. rst:role:: file Имя файла или каталога. В содержимом роли Вы можете использовать фигруные скобки для указания "изменчивой" части пути, например:: ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... В готовой документации ``x`` будет показан изменённым образом, чтобы обозначить, что тут должен находиться номер минорной версии Python. .. rst:role:: guilabel Метки являются частью интерактивного пользовательского интерфейса должны быть помечены как ``guilabel``. Это включает и метки текстовых интерфейсов, таких, как создаваемые при помощи :mod:`curses` или других текстовых библиотек. Все метки, используемые в интерфейсе должны быть помечены этой ролью, включая метки кнопок, заголовков окон, названий полей, меню и даже значений в списках выбора. .. versionchanged:: 1.0 Клавиши быстрого доступа для GUI меток могут быть добавлены при помощи амперсанда; при выводе он будет удалён, а соответствующая буква будет подчёркнута (например: ``:guilabel:`&Cancel```). Для вставки самого амперсанда удвойте его. .. rst:role:: kbd Отмечает последовательность нажатий клавиш. Форма этой последовательности может зависить от платформы или приложения. Если каких-либо договорённостей нет, то следует указать полное название клавиши-модификатора, чтобы помочь новым пользователям и не носителям языка. Например, последовательность клавиш для *xemacs* может быть обозначена как ``:kbd:`C-x C-f```, но без ссылки на конкретное приложение/платформу ту же самую последовательность стоит обозначить как ``:kbd:`Control-x Control-f```. .. rst:role:: mailheader Имя почтового заголовка в стиле RFC 822. Эта разметка не означает, что заголовок используется в почтовом сообщении, но его можно использовать для ссылки на любой заголовок того же самого "стиля". Он так же используется для заголовков, определяемых различными MIME спецификациями. Имя заголовка должно быть введено так же, как если бы оно использовалось в деле с предпочтительным использованием CamelCase (where there is more than one common usage). Например: ``:mailheader:`Content-Type```. .. rst:role:: makevar Имя переменных команды :command:`make`. .. rst:role:: manpage Ссылка на Unix manual page, включая раздел, то есть ``:manpage:`ls(1)```. .. rst:role:: menuselection Выборы меню должны быть помечены при помощи роли ``menuselection``. Она используется для пометки полной последовательности выборов меню, подменю и конкретных операций. Или любых последовательностей этих последовательностей. Имена отдельных выборов должны быть разделены при помощи ``-->``. Например, для отметки выбора "Start > Programs", используйте следующую разметку:: :menuselection:`Start --> Programs` Если Вы включаете выборы, которые содержат какие-то индикаторы в конце имени, как, например, многоточие, которое на некоторых системах означает, что данный пункт меню открывает диалог, эти индикаторы должны быт опущены. ``menuselection`` так же поддерживает использование амперсанда, как и :rst:role:`guilabel`. .. rst:role:: mimetype Имя MIME типа, или компонента MIME типа (старшей или младшей части по отдельности). .. rst:role:: newsgroup Имя Usenet newsgroup. .. rst:role:: program Имя исполняемой программы. Может отличаться от имени файла на некоторых платформах. В частности, на Windows может быть опущено расширение ``.exe`` (или другое). .. rst:role:: regexp Регулярное выражение. Кавычки выключать не надо. .. rst:role:: samp Кусок текста или кода. В содержимом можно использовать фигурные скобки для обозначения "изменяемой" части, как в :rst:role:`file`. Например, в ``:samp:`print 1+{variable}```, часть ``variable`` будет выделена. Если Вам не нужно обозначать "изменяемую часть", тогда используйте станданый ````code````. Кроме того, есть роль :rst:role:`index` для создания элементов индекса. Следующие роли создают внешине ссылки: .. rst:role:: pep Ссылка на Python Enhancement Proposal. Создаёт соответствующий элемент индекса. Генерирует текст "PEP *number*\ "; в HTML выводе этот текст является гиперссылкой на он-лайн копию данного PEP. Вы можете создать ссылку на определённый раздел при помощи ``:pep:`number#anchor```. .. rst:role:: rfc Ссылка на Internet Request for Comments. Создаёт соответствующий элемент индекса. Генерирует текст "RFC *number*\ "; в HTML выводе этот текст является гиперссылкой на он-лайн копию данного RFC. Вы можете создать ссылку на определённый раздел при помощи ``:rfc:`number#anchor```. Обратите внимание, что нет никаких специальных ролей для добавления гиперссылок, так как для этого можно использовать стандартную разметку reST. .. _default-substitutions: Подстановки ~~~~~~~~~~~~~ Система документации предоставляет три подстановки, которые определены по умолчанию. Они задаются в конфигурационном файле "сборщика". .. describe:: |release| Заменяется релизом проекта, который описывается в документации. Это должна быть строка с полной версией, включая теги alpha/beta/release/candidate, например, ``2.5.2b3``. Задаётся :confval:`release`. .. describe:: |version| Заменяется версией проекта, который описывается в документации. Это должна быть строка только с мажорным и минорным номером версии, например, ``2.5`` даже для версии 2.5.1. Задаётся :confval:`version`. .. describe:: |today| Заменяется либо текущей датой (датой, когда прочитывается документ), или датой, заданой в конфигурационном файле. Обычно имеет формат ``April 14, 2007``. Задаётся при помощи :confval:`today_fmt` и :confval:`today`.