> **Источник:** https://python-all.ru/3.0/documenting/rest.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Введение в reStructuredText

Этот раздел представляет собой краткое введение в концепции и синтаксис reStructuredText (reST), предназначенное для того, чтобы дать авторам достаточно информации для продуктивной работы с документацией. Поскольку reST был разработан как простой и ненавязчивый язык разметки, это не займет много времени.

> **См. также**
>
> Авторитетная [документация пользователя reStructuredText](https://python-all.ru/3.0/documenting/rest.html).

## Абзацы

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

## Строчная разметка

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

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

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

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

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

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

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

## Списки и цитаты

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

```rest
* 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.
```

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

```rest
* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues
```

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

```rest
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.
```

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

## Исходный код

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

```rest
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.
```

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

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

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

## Гиперссылки

### Внешние ссылки

Используйте `` `Link text <http://target>`_ `` для встроенных веб-ссылок. Если текстом ссылки должен быть веб-адрес, специальная разметка не нужна: анализатор находит ссылки и почтовые адреса в обычном тексте.

### Внутренние ссылки

Внутренние ссылки создаются с помощью специальной роли reST; см. раздел о конкретной разметке, [*Cross-linking markup*](https://python-all.ru/3.0/documenting/markup.html#doc-ref-role).

## Разделы

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

```rest
=================
This is a heading
=================
```

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

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

## Явная разметка

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

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

## Директивы

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

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

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

   Return a line of text input from the user.
```

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

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

## Примечания

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

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

.. rubric:: Footnotes

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

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

## Комментарии

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

## Кодировка исходного текста

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

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

## Подводные камни

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

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