Шпаргалка по reStructuredText

Введение: Что такое reStructuredText?

reStructuredText (RST) - это язык разметки с открытым исходным кодом. Он разработан в рамках проекта Docutils.

Важно отметить, что RST стал стандартом де-факто для документации в экосистеме Python. Кроме того, он используется по умолчанию в генераторе документации Sphinx.

Ключевые преимущества reStructuredText

Когда целесообразно использовать RST?

• Во-первых, для документации проектов на Python.
• Во-вторых, для технических руководств, спецификаций и API-документации.
• В-третьих, если проект использует Sphinx для сборки документации.
• Наконец, когда важна строгая структура и семантика контента.

Популярные альтернативы

• Markdown - проще для базовых задач, но менее выразителен для технической документации.
• AsciiDoc - более мощный инструмент, однако имеет более сложный синтаксис.

💡 Совет: Если ваш проект уже использует Sphinx - оставайтесь на RST. Для простых README-файлов можно рассмотреть Markdown.

Структура документа: логика и иерархия

Логическая структура документа строится на иерархии заголовков и директив.

Для начала, рекомендуется начинать с оглавления. Затем последовательно раскрывать темы. Таким образом, читатель легко ориентируется в материале.

Основы разметки reStructuredText

reStructuredText - это язык разметки текста. Он используется по умолчанию в Sphinx.

Ниже представлены ключевые элементы синтаксиса с примерами.

Полезные ссылки на документацию

• Sphinx: Markup (reStructuredText)
• Docutils: Quick reStructuredText
• Docutils: Documentation
• Sphinx: reStructuredText Basics
• RST Cheatsheet (GitHub)

Заголовки и уровни вложенности

Заголовки подчёркиваются неалфавитно-цифровым символом. При этом длина подчёркивания должна быть не менее длины текста заголовка.

Важно: одиночный заголовок верхнего уровня автоматически становится заголовком документа.

Соглашение Python по символам заголовков

Можно использовать любой неалфавитно-цифровой символ. Однако соглашение Python рекомендует следующую иерархию:

Пример использования:

==================
Заголовок уровня 1
==================

> ⚠️ Длина разметки иерархии должна быть не короче текста заголовка

Подраздел
-

Под-подраздел
^^^^^^^^^^^^^

⚠️ Обратите внимание: порядок символов определяет уровень вложенности, а не сам символ.

Абзацы и базовое форматирование

Правила оформления параграфов

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

Это первый абзац.

Это второй абзац, отделённый пустой строкой.

Строчная разметка: курсив, жирный, код

*курсив* - одна звёздочка
**жирный** - две звёздочки
``код`` - обратные кавычки

Важно: если звёздочки или обратные кавычки встречаются в тексте, их необходимо экранировать обратной косой чертой: \*, ```.

Ограничения строчной разметки

• Во-первых, разметка не может быть вложенной: **жирный и *курсив* внутри** - не работает.
• Во-вторых, она не может начинаться или заканчиваться пробелом: * текст* - неверно.
• Наконец, разметка должна быть отделена от окружающего текста небуквенными символами:

.thisis\ *one*\ word

💡 Часть встроенной разметки можно расширить с помощью ролей (см. раздел "Роли" ниже).

Списки, цитаты и специальные блоки

Маркированные и нумерованные списки

* Это маркированный список.
* Второй элемент,
продолжающийся на новой строке.

1. Нумерованный список.
2. Второй пункт.

#. Автоматическая нумерация.
#. Следующий пункт.

Вложенные списки: правила отступов

* Родительский элемент
* Ещё один

* Вложенный элемент
* И ещё один

* Продолжение родительского списка

⚠️ Важно: вложенные списки должны отделяться от родительских пустой строкой.

Списки определений

термин
Описание термина с отступом.
Может содержать несколько абзацев.

следующий термин
Его описание.

Цитаты и блоки строк

Простой отступ создаёт блок цитаты:

Основной текст.

Это цитата, выделенная отступом.

Блоки строк сохраняют переносы:

| Эти строки
| разделены точно так же,
| как в исходном файле.

Специальные блоки

• Списки полей (см. ниже)
• Списки опций
• Литеральные блоки
• Блоки doctest

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

Списки полей используются для семантической разметки параметров. Особенно часто они применяются в docstrings.

:param my_arg: Первый аргумент функции.
:param my_other_arg: Второй аргумент.
:returns: Возвращаемое значение.
:raises ValueError: Если аргумент некорректен.

Пример в docstring:

def my_function(my_arg, my_other_arg):
"""Функция для примера.

:param my_arg: Первый аргумент.
:param my_other_arg: Второй аргумент.
:returns: Сообщение.
"""

💡 Стоит отметить: Sphinx расширяет стандартное поведение Docutils и обрабатывает списки полей в начале документов.

Литеральные блоки и примеры кода

Базовый синтаксис блоков кода

Вводятся маркером :: в конце абзаца. При этом содержимое блока должно иметь отступ:

Это обычный текст. Далее - пример кода::

# Код с отступом
def hello():
print("Hello, world!")

Снова обычный текст.

Поведение маркера ::

💡 Совет: подсветка синтаксиса настраивается через директиву .. code-block:: или параметр highlight_language в конфигах.

Блоки doctest для тестирования

Интерактивные сеансы Python используются для тестирования примеров:

>>> 1 + 1
2

>>> print("Hello")
Hello

⚠️ Важно: блок должен заканчиваться пустой строкой. Не оставляйте неиспользованных приглашений >>>.

Таблицы: форматы и лучшие практики

Таблицы с сеткой (ручное форматирование)

+-+-+-+
| Заголовок 1 | Заголовок 2| Заголовок 3|
+================+============+==========+
| Ячейка 1 | Ячейка 2 | Ячейка 3 |
+-+-+-+

Простые таблицы

===== ===== =======
A B A и B
===== ===== =======
False False False
True False False
===== ===== =======

⚠️ Ограничение: простые таблицы не поддерживают многострочные ячейки в первом столбце.

Альтернативы: декларативные директивы

• .. csv-table:: - импорт данных из CSV-файла.
• .. list-table:: - декларативное описание структуры (см. раздел "Популярные директивы").

Гиперссылки: внешние и внутренние

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

`Текст ссылки `_

⚠️ Обязательно: пробел между текстом и ``.

Автоматические ссылки: парсер распознает URL и email в обычном тексте.

Разделённые ссылки:

Смотрите `эту ссылку`_ для деталей.

.. _эту ссылку: https://example.com

Внутренние ссылки и кросс-референсы

Используйте роли Sphinx для перекрёстных ссылок:

:ref:`label-name` - ссылка на раздел с меткой
:numref:`fig1` - ссылка на рисунок с номером

Пример ссылки на рисунок:

См. структуру иконки (:numref:`5Pic6`).

.. _5Pic6:
.. figure:: Img/New_icon1.png
:scale: 80%
:align: center

*Новая иконка в Редакторе*

Подробнее о ролях

Роли: семантическое форматирование текста

Роли - это встроенная разметка для семантического форматирования. Синтаксис: :role:content``.

Стандартные роли Docutils

💡 Важно: Sphinx добавляет собственные роли: :ref:, :doc:, :mod:, :class: и др.

Явная разметка: директивы, сноски, комментарии

Блоки явной разметки начинаются с .. (две точки + пробел). При этом они заканчиваются абзацем с тем же уровнем отступа.

Основные области применения:

• Сноски
• Комментарии
• Директивы
• Замены (substitutions)

.. Это комментарий

.. [1] Сноска

.. directive:: argument
:option: value

Содержимое директивы

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

Директивы: механизм расширения RST

Директивы - это мощный механизм расширения RST.

Базовый синтаксис:

.. directive-name:: arguments
:option1: value1
:option2: value2

Содержимое директивы

Полный список директив Sphinx

Работа с изображениями и медиа

Базовый синтаксис вставки изображений

.. image:: path/to/image.png
:scale: 80%
:align: center
:alt: Альтернативный текст

Особенности работы в Sphinx

• Во-первых, пути могут быть относительными (../images/pic.png) или абсолютными (/images/pic.png).
• Во-вторых, при сборке изображения копируются в выходную директорию.
• В-третьих, поддерживаются шаблоны: .. image:: logo.* - Sphinx выберет подходящий формат для целевого вывода.
• Наконец, единицы измерения: px - для пиксельных форматов, pt, cm, in - для LaTeX/HTML.

⚠️ Важно: имена файлов не должны содержать пробелов.

Сноски, цитаты и замены текста

Сноски (Footnotes)

Текст сноска [#f1]_ и ещё одна [#f2]_.

.. rubric:: Сноски

.. [#f1] Текст первой сноски.
.. [#f2] Текст второй сноски.

Варианты оформления:

• [#name]_ - именованная сноска с автоматической нумерацией.
• [1]_ - явно пронумерованная сноска.
• [#]_ - полностью автоматическая нумерация.

Цитаты (Citations)

Согласно источнику [Ref]_, это важно.

.. [Ref] Автор, "Название", Год. URL

💡 Стоит отметить: цитаты глобальны - на них можно ссылаться из любого файла проекта.

Замены (Substitutions) для повторного использования

Замены позволяют переиспользовать фрагменты текста или разметки:

.. |warning_icon| image:: warning.png
:alt: ⚠️

Использование: |warning_icon| Внимание!

Глобальные замены:

• Добавьте в rst_prolog / rst_epilog в conf.py.
• Или используйте .. include:: для подключения общего файла.

💡 Полезно знать: Sphinx предоставляет встроенные замены: |version|, |release|, |today|.

Комментарии и метаданные

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

.. Это однострочный комментарий

..
Это
многострочный
комментарий

⚠️ Важно: комментарии не попадают в итоговую документацию.

HTML-метаданные для SEO

Директива .. meta:: добавляет ``-теги в HTML-вывод:

.. meta::
:description: Описание документации
:keywords: Sphinx, RST, документация
:keywords lang=en: Sphinx, documentation
:keywords lang=ru: документация, RST

Результат в HTML:

💡 Совет: ключевые слова добавляются в поисковый индекс Sphinx с учётом языка.

Кодировка и локализация

Настройка исходной кодировки

Sphinx по умолчанию предполагает UTF-8.

При необходимости измените в conf.py:

source_encoding = 'utf-8-sig' # например, для BOM

Поддержка многоязычности

• Используйте параметр language = 'ru' в конфигурации.
• Кроме того, применяйте :language: роли для разметки фрагментов.
• Таким образом, документация будет корректно индексироваться поисковыми системами.

Конфигурация Sphinx: ключевые параметры

Базовые настройки в conf.py

# Основная информация
project = 'Документация на ПО'
copyright = '2026, ООО "РОМАШКА"'
author = 'ООО "РОМАШКА"'
release = '1.0.0'
version = '1.0'
master_doc = 'index'

Расширения и функциональность

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
]

pygments_style = 'sphinx'
todo_include_todos = True

Настройки вывода и локализации

templates_path = ['_templates']
language = 'ru'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# HTML-тема
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'logo_only': True,
'display_version': True,
'collapse_navigation': False,
'sticky_navigation': True,
}
html_static_path = ['_static']

LaTeX-конфигурация для PDF

latex_elements = {
'maxlistdepth': '20',
'papersize': 'a4paper',
'releasename': ' ',
'figure_align': 'htbp',
'fontenc': '\\usepackage[T2A]{fontenc}',
'inputenc': '\\usepackage[utf8]{inputenc}',
'babel': '''\\usepackage[russian]{babel}
\\usepackage[dvipsnames,table,xcdraw]{xcolor}''',
}

Популярные директивы: практические примеры

.. toctree:: - создание оглавления

.. toctree::
:maxdepth: 2
:caption: Содержание

intro
usage
api/index

.. figure:: - изображение с подписью и ссылкой

.. _2Pic1:
.. figure:: Img/Scheme_sidebar.png
:scale: 80%
:align: center

*Кнопка "Схемы" в сайдбаре*

.. glossary:: - глоссарий терминов

.. glossary::

API
Application Programming Interface - интерфейс программирования приложений.

Sphinx
Генератор документации, использующий reStructuredText.

Блоки заметок и предупреждений

.. note:: Модель данных - это совокупность структур данных и операций их обработки.

.. warning:: Не изменяйте конфигурацию без согласования.

.. danger:: Не рекомендуется к использованию. Предназначено только для разработчиков.

.. list-table:: - декларативная таблица

.. list-table:: Параметры схемы связей
:widths: 60 80
:header-rows: 1

* - Название параметра
- Описание
* - Таблица связей
- | Обязательный параметр.
| Идентификатор таблицы связей.

.. code-block:: - блок кода с подсветкой синтаксиса

.. code-block:: javascript
:linenos:
:caption: Пример конфигурации

const config = {
endpoint: 'https://api.example.com',
timeout: 5000
};

Заключение и рекомендации

Итак, reStructuredText предоставляет мощный и гибкий инструментарий для технической документации.

В результате правильного использования вы получите:

• Во-первых, структурированную и семантически насыщенную документацию.
• Во-вторых, автоматическую генерацию кросс-ссылок и оглавлений.
• В-третьих, поддержку множества форматов вывода.
• Наконец, лёгкую интеграцию с инструментами Python-экосистемы.

💡 Финальный совет: начинайте с малого, используйте стандартные директивы, и постепенно осваивайте расширенные возможности Sphinx. Таким образом, ваша документация будет расти вместе с проектом.