Руководство по Sphinx: установка, настройка и создание документации

Sphinx — один из самых популярных инструментов для генерации документации в экосистеме Python. Это свободное и открытое ПО умеет извлекать текст из кода и файлов разметки и преобразовывать его в HTML, PDF, EPUB и другие форматы. Sphinx хорошо подходит для проектов, где важна связность документации: автоматические ссылки на функции, классы и термины словаря облегчают навигацию.

Что такое Sphinx и зачем он нужен

Sphinx — генератор документации. По умолчанию он использует разметку reStructuredText (RST), но через расширения может обрабатывать Markdown (например, через myst-parser). Sphinx конвертирует RST/Markdown в HTML, PDF, man-страницы и другие форматы.

Ключевые возможности Sphinx:

• Генерация документации из исходного кода (autodoc).
• Кросс-ссылки на функции, классы, цитаты и термины глоссария.
• Подсветка синтаксиса для блоков кода.
• Поддержка тем оформления и кастомных шаблонов.
• Простая структура и дерево документов через директиву toctree.
• Подключаемые расширения для тестирования сниппетов и проверки ссылок.

Важно: Sphinx — это «documentation-as-code»: документация хранится в репозитории, проверяется в CI и версионируется вместе с кодом.

Установка Sphinx

Перед установкой убедитесь, что в среде установлен Python 3. Рекомендуется использовать виртуальное окружение (venv или virtualenv).

Установка через pip:

pip install sphinx

После установки проверьте версию:

sphinx-build --version

Если всё установлено корректно, команда выведет номер версии Sphinx.

Советы по установке:

• Используйте requirements.txt или pyproject.toml для воспроизводимости окружения.
• В CI добавьте кэширование пакетов pip и/или wheel-артефактов для ускорения сборки.

Создание нового проекта Sphinx

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

sphinx-quickstart

sphinx-quickstart задаст вопросы о проекте (название, автор, формат вывода и т.д.) и создаст структуру: конфигурационный файл conf.py, корневую страницу index.rst и Makefile (make.bat для Windows). Папка build будет содержать сгенерированную документацию.

Файлы, которые вы увидите:

• conf.py — настройки Sphinx.
• index.rst — стартовая страница (главная) документации.
• makefile / make.bat — сценарии сборки.

Структура главной страницы и toctree

index.rst — домашняя страница проекта. Откройте её в VS Code или другом редакторе и убедитесь, что в ней присутствует корневая директива toctree. Эта директива формирует дерево навигации и связывает несколько файлов в одну иерархию.

Пример index.rst для модуля math_utils (переведён и адаптирован):

Welcome to Math Utils
======================

.. toctree::
   :maxdepth: 2

Getting Started
---------------

To use this module, you'll need the following:

* Python installed.
* A text editor

Math Utils
----------

The `math-utils` module provides basic math functions like addition and
subtraction.

Вы можете добавлять произвольное количество файлов .rst или .md, например contributing.rst с инструкцией по внесению изменений.

Пример contributing.rst:

Contributing Guide
==================

We welcome contributions to our project! Here are some guidelines for
contributing:

- Fork the project on GitHub.
- Make your changes on a new branch.
- Write tests to ensure that your changes work correctly.
- Submit a pull request with your changes.
- Make any requested changes.

Thank you for contributing!

Чтобы связать страницу с toctree, добавьте её имя в директиву:

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents

   contributing

Это добавит элемент в оглавление и позволит пользователю перейти на страницу CONTRIBUTING.

Сборка документации

Для генерации HTML выполните команду в корне проекта (там, где Makefile):

make html

После этого HTML-файлы появятся в папке build. Если при сборке возникли ошибки, Sphinx выведет их в терминал.

Откройте в браузере файл build/html/index.html, чтобы просмотреть результат:

Проверьте, что из оглавления доступна страница contributing.

Кастомизация: темы и стили

Sphinx поддерживает встроенные темы и позволяет создавать собственные. Чтобы сменить тему, откройте conf.py и измените параметр html_theme.

Пример смены темы на «nature» (в conf.py):

# conf.py
html_theme = 'nature'

Сохраните файл и перестройте документацию (make html), чтобы увидеть изменения.

Популярные расширения и темы, которые стоит рассмотреть:

• sphinx.ext.autodoc — генерация API из докстрингов.
• sphinx.ext.napoleon — поддержка Google- и NumPy-стиля докстрингов.
• myst-parser — обрабатывать Markdown как входной формат.
• sphinx-rtd-theme, pydata-sphinx-theme — готовые современые темы.

Пример минимального набора расширений в conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'myst_parser',
]

Документирование кода через докстринги

Докстринги размещаются в исходниках Python и описывают назначение модулей, функций и классов. Sphinx может генерировать документацию из них через autodoc.

Пример использования autodoc в .rst файле:

Math Utils API
===============

.. automodule:: math_utils
   :members:
   :undoc-members:
   :show-inheritance:

Хорошая практика: писать докстринги в понятном стиле (Google/NumPy), включать короткий пример использования и отмечать возможные исключения.

Проверка качества документации

Включайте автоматические проверки в CI:

• Сборка документации (make html) должна проходить без ошибок.
• Проверка ссылок (sphinx-build -b linkcheck) для выявления битых внешних ссылок.
• Статический анализ орфографии (sphinxcontrib-spelling).
• Прогон примеров (sphinx.ext.doctest или тесты, запускающие сниппеты).

Критерии приёмки

• Документация собирается локально и в CI без ошибок.
• Все внешние ссылки проходят проверку linkcheck.
• Примеры кода в докстрингах проходят doctest/юнит-тесты.
• Наличие оглавления и навигации по основным разделам.

Мини‑методология: как вести документацию с Sphinx (шаги)

1. План: опишите целевую аудиторию, виды документов (быстрый старт, руководство по API, вкладчикам).
2. Писать: держите небольшие страницы (500–1500 слов), используйте примеры, ясные заголовки и короткие абзацы.
3. Собрать: запускайте make html локально и в CI; собирайте артефакты документации.
4. Проверить: линкчек, орфография, выполнение примеров.
5. Публикация: разместите результат на Read the Docs или в GitHub Pages.

Ментальные модели и эвристики

• Single source of truth: держите документацию близко к коду, в одном репозитории.
• Документация как код: ревью, CI, versioning — все как для исходников.
• Документация прежде объясняет «почему» и «как пользоваться», код — «как реализовано».

Альтернативные подходы и когда их выбирать

• MkDocs — проще для Markdown‑ориентированных проектов; если вы предпочитаете простую конфигурацию и темы на основе Markdown, MkDocs часто быстрее в настройке.
• Docusaurus — хорош для проектов с большой фронтенд-ориентированной документацией и React-плагинами.
• pdoc — минималистичный инструмент для API-документации Python.

Выбор зависит от требований: нужен ли вам автогенерация из докстрингов, поддержка сложных кросс-ссылок и расширяемость — выбирайте Sphinx.

Чек‑листы по ролям

Для поддержания качества документации полезны чек-листы для каждой роли.

Maintainer (поддерживающий проект):

• Обновил conf.py и расширения при необходимости.
• Проверил сборку в CI и локально.
• Настроил публикацию (Read the Docs / GH Pages).
• Контролирует состояние linkcheck.

Contributor (тот, кто пишет контент):

• Добавил/обновил соответствующие .rst/.md файлы.
• Написал или обновил докстринги в коде.
• Добавил примеры и тесты для них.
• Запустил make html локально и убедился в отсутствии ошибок.

Reviewer (код-ревьювер документации):

• Проверил структуру toctree и навигацию.
• Проверил корректность API-ссылок и примеров.
• Оценил читаемость и полноту описания для целевой аудитории.

Шпаргалка команд и конфигураций

Общие команды:

pip install sphinx
sphinx-quickstart
sphinx-build --version
make html
sphinx-build -b linkcheck . _build/linkcheck

Минимальный конфиг: добавьте в conf.py:

project = 'My Project'
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'myst_parser']
html_theme = 'furo'

Если используете Markdown (MyST):

extensions += ['myst_parser']
myst_enable_extensions = ['deflist', 'tasklist']

Тесты и приёмка

Примеры тестовых критериев (acceptance):

• make html выполняется без ошибок.
• doctest в документации проходит.
• linkcheck возвращает 0 как код результата.
• Автодок построил API-страницы с перечислением всех публичных функций.

Глоссарий (1 строка)

• autodoc — расширение Sphinx для генерации документации из докстрингов.
• toctree — директива, формирующая дерево оглавления в Sphinx.
• conf.py — файл конфигурации Sphinx проекта.

Когда Sphinx не лучший выбор

• Проекты, полностью ориентированные на Markdown и минимальную конфигурацию: рассмотрите MkDocs.
• Когда нужен тесный интегрированный фронтенд с React-компонентами: Docusaurus может быть удобнее.

Заключение

Sphinx остаётся мощным инструментом для проектов с Python-кодом, где важна интеграция докстрингов, кросс-ссылки и расширяемость. Он требует небольшого порога вхождения, но даёт гибкость и контроль: от простого сайта документации до сложных справочных систем.

Краткая сводка:

• Установите Sphinx через pip и запустите sphinx-quickstart.
• Пишите документацию в RST или Markdown (MyST) и держите её рядом с кодом.
• Используйте autodoc и napoleon для автоматической генерации API.
• Настройте CI для сборки, linkcheck и тестирования примеров.

Важно: начните с простого набора страниц и постепенно расширяйте структуру, поддерживая документацию в составе процессов разработки.