Sphinx — это генератор документации, который читает исходники в формате reStructuredText и собирает из них статический сайт, PDF, EPUB или man-страницы. Он работает как компилятор: текст лежит в Git, сборка запускается одной командой, а результат одинаков на ноутбуке и в CI. В этой статье — практический маршрут от пустого каталога до публикации сайта с автоматической проверкой ссылок.

Почему Sphinx, а не редактор с экспортом

Markdown-редакторы удобны для заметок, но плохо справляются с большой базой знаний: в них нет нативных перекрёстных ссылок между страницами, оглавления по дереву документов, автодокументирования кода и проверки битых ссылок. Sphinx даёт всё это из коробки. Исходники остаются обычными текстовыми файлами, а значит, проходят ревью в пулл-реквестах и не ломают историю.

Когда Sphinx действительно нужен:

  • у проекта десятки страниц и требуется единое оглавление;
  • документация должна обновляться вместе с кодом;
  • важна проверка ссылок и сборка без предупреждений в CI.

Установка и первый проект

Ставьте Sphinx в виртуальное окружение проекта, чтобы версия не зависела от системного Python. Каталог документации удобно держать рядом с кодом, в docs/.

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install sphinx furo sphinx-autobuild
sphinx-quickstart docs

Мастер спросит имя проекта, автора и язык; для большинства проектов достаточно разделить source и build и указать ru. В результате появится docs/source/conf.py, index.rst и Makefile.

Структура проекта и conf.py

Главный файл настроек — conf.py. Его стоит держать минимальным: лишние параметры усложняют переезд на новую версию. Рабочий набор для русскоязычного проекта выглядит так:

project = "Документация сервиса"
author = "Команда разработки"
language = "ru"
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosummary",
]
html_theme = "furo"
html_static_path = ["_static"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
nitpicky = True

Параметр nitpicky = True заставляет сборку ругаться на неразрешённые ссылки. Включать его лучше сразу: позже, когда страниц станет сотня, искать битые ссылки вручную уже поздно.

Дерево документации задаётся директивой toctree в index.rst. Файлы, не попавшие в дерево, не выводятся в навигации, хотя и собираются.

Основы reStructuredText

RST строже Markdown, и это его сила: структура однозначна, а ошибки видны при сборке. Заголовки подчёркиваются символами, причём уровень определяется порядком появления, а не самим символом. Придерживайтесь одной схемы: = для раздела, - для подраздела.

Установка сервиса
=================

Требования
----------

Нужны Python 3.12 и доступ к репозиторию.

.. code-block:: bash
   :linenos:

   systemctl status nginx
   journalctl -u nginx -n 50

.. note::

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

.. warning::

   Команда удаляет каталог без возможности отмены.

Список возможностей:

* быстрый поиск;
* офлайн-режим;
* экспорт в PDF.

Отступ в директиве обязателен: он отделяет содержимое code-block от самой директивы, а не служит оформлением. Если отступ «поехал», Sphinx либо выдаст предупреждение, либо включит код в абзац. Для таблиц используйте list-table: сложная вёрстка только мешает чтению.

Ссылки, глоссарий и нумерация

Главное преимущество Sphinx — ссылки, которые проверяются при сборке. Для ссылки на документ используется :doc:, для метки внутри текста — :ref:, для термина — :term:. Метка ставится перед заголовком:

.. _deploy-label:

Развёртывание
=============

Смотрите :doc:`/setup/install` и раздел :ref:`deploy-label`.
Термин :term:`обратный прокси` описан в глоссарии.

.. glossary::

   обратный прокси
      Сервер, принимающий запросы и передающий их бэкенду.

Если файл переименовали, сборка с nitpicky сразу покажет битую ссылку. Для внешних ресурсов подключайте intersphinx — ссылки на стандартную библиотеку останутся рабочими.

Автодокументирование кода

Чтобы описания функций не дублировались вручную, используйте autodoc. Sphinx импортирует модуль и вытаскивает docstring. Важно, чтобы пакет был доступен при сборке: добавьте путь в sys.path или установите проект командой pip install -e . в окружение.

import os
import sys
sys.path.insert(0, os.path.abspath("../src"))

autodoc_default_options = {
    "members": True,
    "undoc-members": False,
    "show-inheritance": True,
}
autodoc_mock_imports = ["psycopg2", "redis"]
napoleon_google_docstring = True

Директива autosummary генерирует отдельные страницы для каждого модуля. Тяжёлые зависимости, которые не нужны для импорта, перечисляйте в autodoc_mock_imports, иначе сборка упадёт на машине без базы данных.

Тема и расширения

Тема furo даёт аккуратную навигацию, тёмный режим и нормальную работу на мобильных. Альтернативы — sphinx-rtd-theme и pydata-sphinx-theme; выбирайте одну и не смешивайте кастомизацию. Полезные расширения: sphinx-autobuild для живого предпросмотра, sphinx-copybutton для кнопки копирования команд, myst-parser для постепенного перехода на Markdown.

Не ставьте десяток расширений «на всякий случай»: каждое — лишняя зависимость. Начните с autodoc, intersphinx и одной темы.

Сборка, проверки и CI

Локальная сборка запускается через make html в каталоге с Makefile. Для живого предпросмотра удобен sphinx-autobuild: он пересобирает страницы при сохранении и открывает браузер. Перед коммитом полезно прогнать сборку с -W: любое предупреждение станет ошибкой.

sphinx-build -b html -W --keep-going source build/html
sphinx-build -b linkcheck source build/linkcheck
sphinx-build -b epub source build/epub

В CI достаточно установить зависимости из requirements.txt и выполнить ту же команду. Артефакт можно сразу опубликовать на статическом хостинге.

name: docs
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r docs/requirements.txt
      - run: sphinx-build -b html -W --keep-going docs/source docs/build/html

Типичные ошибки и чек-лист

  • Файл не добавлен в toctree — страница есть, но её не найти в меню.
  • Неверный отступ в директиве — код становится обычным абзацем.
  • Пакет не установлен в окружение — autodoc падает при импорте.
  • Ссылка ведёт на переименованный файл — нужна проверка -W.
  • Тема переопределяет стили без нужды — обновление ломает вёрстку.

Итог

Sphinx стоит осваивать, если документация живёт дольше одного спринта. Минимальный набор — виртуальное окружение, conf.py с autodoc и intersphinx, тема Furo и сборка с -W в CI. RST требует аккуратности, но взамен даёт проверяемые ссылки, единое оглавление и несколько форматов вывода из одного источника. Начните с трёх страниц и одного модуля, а расширения добавляйте по мере роста проекта.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте