Install Sphinx

Install Sphinx#

Шаг 1: Установка необходимых пакетов#

pip install sphinx sphinx-rtd-theme myst-parser

  • sphinx - основной движок документации

  • sphinx-rtd-theme - популярная тема Read the Docs

  • myst-parser - парсер для работы с Markdown файлами

Шаг 2: Создание структуры проекта#

mkdir docs
cd docs
sphinx-quickstart

При запуске sphinx-quickstart ответьте на вопросы:

  • Separate source and build directories? → y (да)

  • Project name → введите название проекта

  • Author name(s) → ваше имя

  • Project release → версия (например, 1.0)

Шаг 3: Настройка conf.py#

Откройте файл docs/source/conf.py и добавьте/измените:

# Добавьте myst_parser в extensions
extensions = [
    'myst_parser',
]

# Укажите, какие форматы файлов поддерживаются
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

# Выберите тему (опционально)
html_theme = 'sphinx_rtd_theme'

Шаг 4: Организация Markdown файлов#

Скопируйте ваши .md файлы в папку docs/source/:

cp /путь/к/вашим/файлам/*.md docs/source/

Шаг 5: Создание главного индекса#

Отредактируйте docs/source/index.rst или создайте index.md:

# Документация проекта

Добро пожаловать в документацию!

## Содержание

```{toctree}
:maxdepth: 2
:caption: Разделы:

file1.md
file2.md
file3.md
```

Шаг 6: Генерация документации#

cd docs
make html

Готовая документация будет в docs/build/html/index.html

Шаг 7: Просмотр результата#

Откройте в браузере:

# Linux/Mac
open build/html/index.html

# Windows
start build/html/index.html

Дополнительные возможности#

Автоматическое обновление при изменениях:

pip install sphinx-autobuild
sphinx-autobuild source build/html

Настройка MyST для расширенных возможностей Markdown в conf.py:

myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "html_image",
]

Сборка с очисткой кеша:#

~$ make clean && make html
Contents