3. Введение в reStructuredText¶reStructuredText Primer

3.1. Абзацы¶Paragraphs

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

3.2. Строчная разметка¶Inline markup

Стандартная строчная разметка reST довольно проста: используйте

• одна звездочка: *text* для выделения (курсив),
• две звездочки: **text** для сильного выделения (полужирный), и
• обратные кавычки: ``text`` для примеров кода.

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

Следует учитывать некоторые ограничения этой разметки:

• она не может быть вложенной,
• содержимое не должно начинаться или заканчиваться пробелом: * text* – это неправильно,
• она должна быть отделена от окружающего текста символами, не являющимися буквами. Используйте экранированный пробел с обратной косой чертой, чтобы обойти это: thisis\ *one*\ word.

Эти ограничения могут быть сняты в будущих версиях docutils.

reST также позволяет использовать пользовательские «роли интерпретируемого текста», которые указывают, что заключенный текст должен интерпретироваться определенным образом. Sphinx использует это для обеспечения семантической разметки и перекрестных ссылок на идентификаторы, как описано в соответствующем разделе. Общий синтаксис: :rolename:`content`.

3.3. Списки и цитаты¶Lists and Quotes

Разметка списков естественна: просто поставьте звездочку в начале абзаца и правильно сделайте отступ. То же самое относится к нумерованным спискам; они также могут быть автоматически пронумерованы с помощью знака #:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Вложенные списки возможны, но следует учитывать, что они должны быть отделены от элементов родительского списка пустыми строками:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Списки определений создаются следующим образом:

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Абзацы цитируются простым увеличением отступа относительно окружающих абзацев.

3.4. Исходный код¶Source Code

Литеральные блоки кода вводятся завершением абзаца специальным маркером ::. Литеральный блок должен иметь отступ:

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Обработка маркера :: разумна:

• Если он встречается как отдельный абзац, этот абзац полностью исключается из документа.
• Если перед ним стоит пробел, маркер удаляется.
• Если перед ним стоит непробельный символ, маркер заменяется на одно двоеточие.

Таким образом, второе предложение в первом абзаце приведенного выше примера будет отображаться как «Следующий абзац – пример кода:».

3.5. Гиперссылки¶Hyperlinks

3.6. Разделы¶Sections

Заголовки разделов создаются подчёркиванием (и, опционально, надчёркиванием) заголовка знаком пунктуации, длиной не менее самого текста:

=================
This is a heading
=================

Обычно определённым символам не присваиваются уровни заголовков, поскольку структура определяется последовательностью заголовков. Однако в документации Python используется следующее соглашение:

• # с надчёркиванием, для частей
• * с надчёркиванием, для глав
• =, для разделов
• -, для подразделов
• ^, для подподразделов
• ", для параграфов

3.7. Явная разметка¶Explicit Markup

«Явная разметка» используется в reST для большинства конструкций, требующих специальной обработки, таких как сноски, специально выделенные абзацы, комментарии и общие директивы.

Блок явной разметки начинается со строки, начинающейся с .., за которой следует пробел, и завершается следующим абзацем на том же уровне отступа. (Между явной разметкой и обычными абзацами должна быть пустая строка. Всё это может звучать немного сложно, но на практике интуитивно понятно.)

3.8. Директивы¶Directives

Директива – это общий блок явной разметки. Наряду с ролями, это один из механизмов расширения reST, который широко используется Sphinx.

В основном директива состоит из имени, аргументов, опций и содержимого. (Запомните эту терминологию – она используется в следующей главе, описывающей пользовательские директивы.) Рассмотрим этот пример:

.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.

function – это имя директивы. Здесь ей передаются два аргумента: остаток первой строки и вторая строка, а также одна опция bar (как видите, опции указываются в строках сразу после аргументов и обозначаются двоеточиями).

Содержимое директивы следует после пустой строки и имеет отступ относительно начала директивы.

3.9. Сноски¶Footnotes

Для сносок используйте [#]_, чтобы отметить место сноски, и добавьте тело сноски внизу документа после заголовка рубрики «Сноски», например:

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

Можно также явно нумеровать сноски для лучшего контекста.

3.10. Комментарии¶Comments

Любой блок явной разметки, не являющийся допустимой конструкцией разметки (как сноски выше), считается комментарием.

3.11. Кодировка исходного кода¶Source encoding

Поскольку самый простой способ включить специальные символы, такие как длинные тире или знаки копирайта, в reST – это прописать их напрямую как символы Unicode, необходимо указать кодировку:

Все исходные файлы документации Python должны быть в кодировке UTF-8, и создаваемые из них HTML-документы также будут в этой кодировке.

3.12. Подводные камни¶Gotchas

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

• Отделение встроенной разметки: Как уже говорилось выше, фрагменты встроенной разметки должны отделяться от окружающего текста небуквенными символами; чтобы обойти это, нужно использовать экранированный пробел.