Документация из кода в Git: приёмы для рабочего процесса

Документация из кода экономит время только тогда, когда её можно проверить вместе с изменениями. Иначе в Git появляется новый метод, а на сайте остаётся старое описание; либо CI месяцами успешно собирает страницы, которые никто не читает. Ниже — практика для Python-проекта на Sphinx 7.x: как хранить исходники документации, подключать API и не превращать сборку в отдельный ритуал.

Сначала выберите, что именно генерировать

Слово «генерация» часто смешивает две разные задачи. Первая — собрать страницы из файлов Markdown или reStructuredText. Вторая — извлечь API из docstring и автоматически создать для него страницы. Sphinx умеет оба варианта: сам генератор не заменит руководство, объясняющее, как пользоваться продуктом.

Для Python-библиотеки практичный вариант — держать вводные страницы в репозитории, а публичные классы и функции подключать через autodoc. Такой подход требует, чтобы пакет импортировался в окружении сборки. Если импорт запускает подключение к базе или требует секретов, сборку документации лучше отделить от таких побочных эффектов, а не подсовывать генератору фиктивные ключи.

Таблица не означает, что нужно выбрать один способ на весь проект. Обычно вводные материалы пишут вручную, а справочник публичного API собирают из кода. Генерацию по спецификации имеет смысл добавлять там, где такой источник уже есть.

Положите сборку рядом с исходниками

Удобная структура позволяет разработчику найти страницу и проверить её изменение в том же pull request, что и код:

• docs/ — исходники страниц и конфигурация Sphinx;
• docs/api/ — страницы, которые подключают модули и объекты из пакета;
• CI — установка зависимостей документации и сборка сайта;
• публикация — отдельный этап, который запускается после проверки, а не вместо неё.

Не коммитьте результат сборки в тот же каталог, где лежат исходники. Иначе изменения в HTML, CSS и служебных файлах затрудняют ревью, хотя автор правил одну строку docstring. Добавьте выходной каталог сборки в исключения Git; точное имя зависит от команды и конфигурации проекта.

В Sphinx 7.x расширение autodoc подключают в конфигурации проекта, а страницу API описывают директивой automodule. Пример рассчитан на Python-пакет, который установлен в окружении сборки:

# docs/conf.py
extensions = [
    "sphinx.ext.autodoc",
]

# docs/api/library.rst
API
===

.. automodule:: library
   :members:
   :undoc-members:

Замените library на импортируемое имя своего пакета. Опция :members: включает документируемые члены модуля, а :undoc-members: добавляет и те, у которых нет docstring. Последнюю обычно не стоит включать без причины: список имён без пояснений создаёт впечатление полного справочника, но почти не помогает читателю.

Проверяйте документацию в том же изменении

Рабочий процесс начинается не с генератора, а с изменения кода. Если у публичной функции поменялись аргументы, автор обновляет docstring или страницу API в том же pull request. Ревьюер видит дифф рядом с реализацией и может проверить, совпадает ли обещанное поведение с фактическим.

1. Определите публичную поверхность. Не публикуйте автоматически каждый внутренний модуль. Отметьте, какие пакеты и объекты поддерживаются как API. Проверка: в списке страниц нет случайных служебных модулей.
2. Напишите описание контракта. Укажите назначение, значимые аргументы, результат и исключения, если они важны для пользователя. Проверка: по описанию можно понять, как вызвать объект и чего ожидать.
3. Добавьте или обновите страницу API. Подключите нужный модуль и проверьте, что он импортируется в чистом окружении. Проверка: локальная сборка не сообщает об ошибке импорта.
4. Запустите сборку с предупреждениями как ошибками. Для Sphinx 7.x базовая команда — sphinx-build -W --keep-going -b html docs docs/_build/html. Проверка: команда завершается с кодом 0, а CI показывает сборку в зелёном статусе.
5. Проверьте читательский путь. Откройте главную страницу и справочник API, пройдите по ссылкам и найдите изменённый объект. Проверка: ссылка ведёт на существующую страницу, а содержание не обрезано.

Флаги -W и --keep-going полезны в CI: предупреждения не проходят незамеченными, а сборка старается показать несколько проблем за один запуск. Но они не проверяют смысл docstring и не гарантируют, что пример действительно отражает поведение программы. Для примеров нужны отдельные тесты либо ручная проверка.

Что обычно ломается

Импорт пакета запускает лишнее

Autodoc импортирует модули, чтобы прочитать объекты. Если импорт при этом пытается подключиться к сервису или читает переменные окружения, локальная сборка и CI могут падать. Исправляйте побочный эффект в архитектуре импорта; не маскируйте его случайными значениями конфигурации.

Страница есть, но генератор её не подхватил

Подключение модуля не всегда означает, что новая страница попадёт в навигацию. Проверьте оглавление проекта и предупреждения Sphinx. Сборка HTML сама по себе не подтверждает, что пользователь найдёт нужную страницу с главной.

Публичный API разрастается без контроля

Автоматически выводить все члены пакета удобно до первого внутреннего класса, который пользователь начинает считать обещанной частью интерфейса. Состав API нужно ограничивать осознанно и проверять при ревью. Иначе удаление внутренней детали превращается в неожиданное изменение для тех, кто на неё уже опирается.

CI собирает документацию, но публикация ломается

Сборка HTML и выкладка сайта — разные этапы. Если публикация зависит от ветки, версии релиза или прав доступа, проверяйте эти условия отдельно. Не храните токены публикации в документации или исходниках: передавайте секреты только через защищённые настройки CI.

Автогенерация убирает ручное копирование API, но не снимает с команды ответственность за его границы и смысл.

Когда какой подход выбирать

• Выбирайте ручные страницы для установки, концепций, миграций и сценариев: их смысл редко удаётся выразить списком сигнатур.
• Подключайте autodoc для стабильного публичного API Python-библиотеки, если модули можно импортировать в окружении сборки.
• Стройте справочник по спецификации, если контракт уже описан формально и именно он служит источником правды для реализации.

Для небольшого пакета не обязательно сразу публиковать сложный сайт. Начните с одного справочника API и сборки в CI. Если команда регулярно меняет публичные интерфейсы, добавьте проверку ссылок и тестирование примеров как отдельные задачи.

Docstring — строка документации в исходном коде Python, обычно размещённая сразу после объявления модуля, класса или функции. Sphinx autodoc читает её вместе с объектами, которые импортирует из проекта.

Что делать дальше

Добавьте одну страницу API и включите сборку Sphinx в обязательные проверки pull request. Затем посмотрите на первые предупреждения и на то, как новый разработчик находит нужный объект по навигации. Следующий полезный показатель — не число сгенерированных страниц, а количество ошибок сборки и ссылок, которые команда исправляет до релиза.