rest.md
1> **Источник:** https://python-all.ru/3.1/documenting/rest.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 3. Введение в reStructuredText89Этот раздел представляет собой краткое введение в концепции и синтаксис reStructuredText (reST), предназначенное для того, чтобы дать авторам достаточно информации для продуктивной работы с документацией. Поскольку reST был разработан как простой и ненавязчивый язык разметки, это не займет много времени.1011> **См. также**12>13> Авторитетная [документация пользователя reStructuredText](https://python-all.ru/3.1/documenting/rest.html).1415## 3.1. Абзацы1617Абзац – это самый базовый блок в документе reST. Абзацы представляют собой просто фрагменты текста, разделенные одной или несколькими пустыми строками. Как и в Python, отступы в reST имеют значение, поэтому все строки одного абзаца должны быть выровнены по левому краю с одинаковым уровнем отступа.1819## 3.2. Строчная разметка2021Стандартная строчная разметка reST довольно проста: используйте2223- одна звездочка: `*text*` для выделения (курсив),24- две звездочки: `**text**` для сильного выделения (полужирный), и25- обратные кавычки: `` ``text`` `` для примеров кода.2627Если звездочки или обратные кавычки встречаются в обычном тексте и могут быть перепутаны с разделителями строчной разметки, их нужно экранировать обратной косой чертой.2829Следует учитывать некоторые ограничения этой разметки:3031- она не может быть вложенной,32- содержимое не должно начинаться или заканчиваться пробелом: `* text*` – это неправильно,33- она должна быть отделена от окружающего текста символами, не являющимися буквами. Используйте экранированный пробел с обратной косой чертой, чтобы обойти это: `thisis\ *one*\ word`.3435Эти ограничения могут быть сняты в будущих версиях docutils.3637reST также позволяет использовать пользовательские «роли интерпретируемого текста», которые указывают, что заключенный текст должен интерпретироваться определенным образом. Sphinx использует это для обеспечения семантической разметки и перекрестных ссылок на идентификаторы, как описано в соответствующем разделе. Общий синтаксис: `` :rolename:`content` ``.3839## 3.3. Списки и цитаты4041Разметка списков естественна: просто поставьте звездочку в начале абзаца и правильно сделайте отступ. То же самое относится к нумерованным спискам; они также могут быть автоматически пронумерованы с помощью знака `#`:4243```rest44* This is a bulleted list.45* It has two items, the second46 item uses two lines.47481. This is a numbered list.492. It has two items too.5051#. This is a numbered list.52#. It has two items too.53```5455Вложенные списки возможны, но следует учитывать, что они должны быть отделены от элементов родительского списка пустыми строками:5657```rest58* this is59* a list6061 * with a nested list62 * and some subitems6364* and here the parent list continues65```6667Списки определений создаются следующим образом:6869```rest70term (up to a line of text)71 Definition of the term, which must be indented7273 and can even consist of multiple paragraphs7475next term76 Description.77```7879Абзацы цитируются простым увеличением отступа относительно окружающих абзацев.8081## 3.4. Исходный код8283Литеральные блоки кода вводятся завершением абзаца специальным маркером `::`. Литеральный блок должен иметь отступ:8485```rest86This is a normal text paragraph. The next paragraph is a code sample::8788 It is not processed in any way, except89 that the indentation is removed.9091 It can span multiple lines.9293This is a normal text paragraph again.94```9596Обработка маркера `::` разумна:9798- Если он встречается как отдельный абзац, этот абзац полностью исключается из документа.99- Если перед ним стоит пробел, маркер удаляется.100- Если перед ним стоит непробельный символ, маркер заменяется на одно двоеточие.101102Таким образом, второе предложение в первом абзаце приведенного выше примера будет отображаться как «Следующий абзац – пример кода:».103104## 3.5. Гиперссылки105106### 3.5.1. Внешние ссылки107108Используйте `` `Link text <http://target>`_ `` для встроенных веб-ссылок. Если текстом ссылки должен быть веб-адрес, специальная разметка не нужна: анализатор находит ссылки и почтовые адреса в обычном тексте.109110### 3.5.2. Внутренние ссылки111112Внутренние ссылки создаются с помощью специальной роли reST; см. раздел о конкретной разметке, [*Cross-linking markup*](https://python-all.ru/3.1/documenting/markup.html#doc-ref-role).113114## 3.6. Разделы115116Заголовки разделов создаются подчёркиванием (и, опционально, надчёркиванием) заголовка знаком пунктуации, длиной не менее самого текста:117118```rest119=================120This is a heading121=================122```123124Обычно определённым символам не присваиваются уровни заголовков, поскольку структура определяется последовательностью заголовков. Однако в документации Python используется следующее соглашение:125126- `#` с надчёркиванием, для частей127- `*` с надчёркиванием, для глав128- `=`, для разделов129- `-`, для подразделов130- `^`, для подподразделов131- `"`, для параграфов132133## 3.7. Явная разметка134135«Явная разметка» используется в reST для большинства конструкций, требующих специальной обработки, таких как сноски, специально выделенные абзацы, комментарии и общие директивы.136137Блок явной разметки начинается со строки, начинающейся с `..`, за которой следует пробел, и завершается следующим абзацем на том же уровне отступа. (Между явной разметкой и обычными абзацами должна быть пустая строка. Всё это может звучать немного сложно, но на практике интуитивно понятно.)138139## 3.8. Директивы140141Директива – это общий блок явной разметки. Наряду с ролями, это один из механизмов расширения reST, который широко используется Sphinx.142143В основном директива состоит из имени, аргументов, опций и содержимого. (Запомните эту терминологию – она используется в следующей главе, описывающей пользовательские директивы.) Рассмотрим этот пример:144145```rest146.. function:: foo(x)147 foo(y, z)148 :bar: no149150 Return a line of text input from the user.151```152153`function` – это имя директивы. Здесь ей передаются два аргумента: остаток первой строки и вторая строка, а также одна опция `bar` (как видите, опции указываются в строках сразу после аргументов и обозначаются двоеточиями).154155Содержимое директивы следует после пустой строки и имеет отступ относительно начала директивы.156157## 3.9. Сноски158159Для сносок используйте `[#]_`, чтобы отметить место сноски, и добавьте тело сноски внизу документа после заголовка рубрики «Сноски», например:160161```rest162Lorem ipsum [#]_ dolor sit amet ... [#]_163164.. rubric:: Footnotes165166.. [#] Text of the first footnote.167.. [#] Text of the second footnote.168```169170Можно также явно нумеровать сноски для лучшего контекста.171172## 3.10. Комментарии173174Любой блок явной разметки, не являющийся допустимой конструкцией разметки (как сноски выше), считается комментарием.175176## 3.11. Кодировка исходного кода177178Поскольку самый простой способ включить специальные символы, такие как длинные тире или знаки копирайта, в reST – это прописать их напрямую как символы Unicode, необходимо указать кодировку:179180Все исходные файлы документации Python должны быть в кодировке UTF-8, и создаваемые из них HTML-документы также будут в этой кодировке.181182## 3.12. Подводные камни183184Существует несколько проблем, с которыми часто сталкиваются при написании документов reST:185186- **Отделение встроенной разметки:** Как уже говорилось выше, фрагменты встроенной разметки должны отделяться от окружающего текста небуквенными символами; чтобы обойти это, нужно использовать экранированный пробел.187