Файл RST

.rst - это текстовый формат облегченной разметки, используемый в основном для технической документации в экосистеме Python. Файлы используют человекочитаемый синтаксис: заголовки разделов создаются путем подчеркивания текста заголовка такими символами, как =, - или ~; примеры кода вводятся с помощью директив .. code-block::; перекрестные ссылки используют синтаксис :role:; а оглавления документов строятся с помощью директив .. toctree::.

По сравнению с Markdown, .rst предоставляет формальную систему директив и ролей, которая обеспечивает более богатую семантическую разметку - сноски, цитаты, настраиваемые примечания, перекрестные ссылки API - без необходимости использования отдельных расширений. Генератор документации Sphinx использует .rst в качестве родного исходного формата и создает официальную документацию для Python, NumPy, Django и ядра Linux из исходных файлов .rst.

Файлы представляют собой обычный текст в кодировке UTF-8 без бинарной структуры или магических байтов, доступный для редактирования в любом текстовом редакторе. Стандартным процессором является Docutils, который преобразует .rst в HTML, LaTeX, PDF и другие форматы с помощью инструментов командной строки, таких как rst2html и rst2latex. Крупные проекты Sphinx связывают сотни отдельных исходных файлов .rst через директивы .. toctree::.

Обычно используемый MIME-тип - text/x-rst; единственный тип, зарегистрированный в IANA, text/prs.fallenstein.rst, не признается самим проектом Docutils. reStructuredText активно поддерживается, хотя новые проекты все чаще выбирают альтернативы на основе Markdown, такие как MyST, для более легких рабочих процессов документации.