reStructuredText для документации Python

Конвертируйте Markdown в RST для Sphinx и проектов Python

reStructuredText (RST) — стандартный формат документации для проектов Python, использующих Sphinx. Хотя Markdown отлично подходит для написания, RST предлагает мощные функции для технической документации. Конвертируя Markdown в RST, вы можете быстро писать в Markdown и интегрироваться с существующими рабочими процессами документации Python.

Зачем конвертировать в RST?

Совместимость со Sphinx — RST является нативным форматом Sphinx
Экосистема Python — большинство документации Python использует RST
Перекрёстные ссылки — RST поддерживает надёжное связывание между документами
Расширения — доступ к мощной экосистеме расширений Sphinx
Read the Docs — прямая интеграция с хостингом RTD

Как это работает

При конвертации Markdown в RST вы получаете правильный синтаксис RST:

Introduction
============

This is a paragraph with **bold** and *italic* text.

* First item
* Second item

Code Example
------------

.. code-block:: python

   def greet(name):
       return f"Hello, {name}!"

Конвертировать в RST

Соответствие Markdown и RST

Markdown	Вывод RST
`# Heading`	Подчёркнут `=====`
`## Subheading`	Подчёркнут `-----`
`bold`	`bold`
`italic`	`italic`
`code`	``code``
`[text](url)`	`text <url>`_
Блоки кода	`.. code-block::`

Использование RST со Sphinx

Базовый рабочий процесс

Пишите контент в Markdown для скорости
Конвертируйте в RST с помощью Markdown2ANY
Добавьте RST-специфичные функции (директивы, перекрёстные ссылки)
Собирайте с помощью Sphinx: sphinx-build -b html source/ build/

Добавление функций RST

После конвертации расширяйте RST директивами Sphinx:

.. note::
   This is a note admonition.

.. warning::
   This is a warning.

.. seealso::
   :doc:`other-document`

Типичные сценарии использования

Документация API

Конвертируйте файлы README и руководства в RST для интеграции с автоматически сгенерированными справочниками API через autodoc.

Обучающие материалы

Пишите обучающие материалы в Markdown, конвертируйте в RST, затем добавьте перекрёстные ссылки на документацию API.

Руководства для контрибьюторов

Создавайте документацию для контрибьюторов, соответствующую формату остальной документации проекта.

RST-специфичные функции

После конвертации вы можете добавить функции RST, которые Markdown не поддерживает:

Блоки-предупреждения — note, warning, tip, danger
Перекрёстные ссылки — связывание между документами и секциями
Роли — семантическая разметка, такая как :func:, :class:
Директивы — пользовательские блоки контента
Toctrees — иерархии документов

Связанные руководства

Markdown для документации ПО — лучшие практики документации
Руководство по основам Markdown — изучите синтаксис Markdown
Выбор подходящего формата вывода — сравнение всех форматов

Конвертировать в RST сейчас