Документация из кода в Git: чек-лист перед продакшеном

Автогенерация документации экономит время, пока не начинает публиковать устаревшие примеры или ломаться на CI. Перед продакшеном проверьте, откуда генератор берёт данные, совпадает ли документация с текущей версией кода и можно ли повторить сборку на чистом окружении. Чек-лист ниже подходит для Git 2.4x и распространённых генераторов — например, Sphinx 7.x и MkDocs 1.x; конкретные команды и параметры сверяйте с документацией выбранной версии.

Сначала определите, что именно генерируется

«Документация из кода» — не один тип страниц. Генератор может собирать справочник по публичным функциям и классам из комментариев, превращать схему API в описание эндпоинтов или строить сайт из файлов Markdown. У этих материалов разные источники правды и разные способы проверки.

Для каждого раздела зафиксируйте источник. Например: описание публичных методов берётся из docstring, список HTTP-эндпоинтов — из спецификации API, а инструкция по развёртыванию хранится в Markdown. Если один и тот же параметр описан в коде и вручную на странице, рано или поздно версии разойдутся.

До выбора инструмента ответьте на три вопроса: кто читатель, какие страницы ему нужны и где они будут опубликованы. Справочник библиотечных функций не заменит руководство для пользователя, а генерация API-референса сама по себе не объяснит, как запустить сервис.

Три подхода и их цена

Для Python-проектов Sphinx и MkDocs решают задачу сборки сайта, но сами по себе не гарантируют правильность описаний. Конкретный способ извлечения документации зависит от расширений и версии. Для TypeScript отдельный генератор может строить справочник из типов и комментариев, но пользовательские инструкции всё равно придётся поддерживать отдельно.

Чек-лист перед включением в продакшен

1. Назначьте источник правды. Для каждой страницы или группы страниц укажите, где редактируются исходные данные: в коде, спецификации или Markdown. Проверка: в репозитории нет двух мест, которые должны независимо описывать один и тот же контракт.
2. Зафиксируйте версии генератора и зависимостей. Укажите их в стандартном для проекта файле зависимостей и собирайте документацию на той же версии в CI. Проверка: чистый запуск сборки не подтягивает случайную новую версию инструмента.
3. Собирайте документацию в pull request. Запускайте тот же процесс, что будет использоваться при публикации. Если генератор только создаёт файлы, проверьте результат; если дополнительно собирается сайт, проверяйте и сборку сайта. Проверка: PR получает понятный статус, а не требует от автора вручную угадывать, прошла ли сборка.
4. Проверяйте не только наличие файлов. Настройте проверки битых ссылок, предупреждений и ошибок генерации, если выбранный инструмент их поддерживает. Проверка: ошибка в ссылке или неизвестный символ приводят к видимому сбою, а не теряются в длинном логе.
5. Разведите версии документации. Для релизной библиотеки читатель должен попасть к описанию своей версии, а не к справочнику последней разработки. Проверка: ссылка из релизных заметок ведёт на соответствующую версию.
6. Посмотрите на результат глазами пользователя. Откройте опубликованный сайт без доступа к репозиторию: проверьте навигацию, мобильную ширину, поиск и примеры. Проверка: незнакомый с кодовой базой читатель находит нужный раздел и понимает, к какой версии он относится.
7. Определите, что коммитится. Решите, хранится ли сгенерированный сайт в Git или публикуется отдельным процессом. Проверка: в PR ясно видно, кто и когда обновляет результат, а временные файлы сборки не засоряют историю.

Что проверить в pull request

Генерация документации не означает, что каждое изменение требует коммита всего собранного сайта. Важно, чтобы изменения исходного кода и связанного описания проходили одной проверкой и были доступны ревьюеру. Если документация версионируется отдельно, укажите, как PR влияет на опубликованные версии.

Для review пригодятся конкретные вопросы:

• Изменился ли публичный интерфейс, схема API или поведение, которое видит пользователь?
• Обновлено ли описание параметров, ограничений и ошибок вместе с изменением?
• Можно ли выполнить пример в заявленной версии продукта?
• Не раскрывает ли сгенерированный справочник внутренние адреса, служебные типы или комментарии для разработчиков?
• Показывает ли предпросмотр именно тот набор страниц, который будет опубликован?

Сгенерированный diff иногда получается большим и шумным. Не принимайте его автоматически только потому, что его создал CI: проверьте, что в нём нет удалённых разделов, пустых страниц и неожиданных изменений навигации.

Генератор отвечает за повторяемость сборки, но не за правдивость документации. Если исходный комментарий неверен, автоматизация быстрее опубликует неверный ответ.

Что чаще всего ломается

Сборка проходит, но описания устарели

Это классический дрейф документации — постепенное расхождение текста и действующего кода или API. CI часто может проверить структуру и ссылки, но не понять, что пример теперь ведёт себя иначе. Добавьте в ревью проверку примеров: запускайте их автоматически там, где это безопасно, или назначайте ответственного за содержимое раздела.

В локальной среде работает, в CI — нет

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

Публикуется не та версия

Если несколько веток или релизов пишут в одно место публикации, документация может перезаписать сама себя. Разделите адреса или процессы по версиям и назначьте единственный источник публикации для каждого адреса. Соседняя тема — устройство конкретного конвейера CI/CD; здесь важно проверить, что релиз не подменяет документацию другой ветки.

Публичный сайт раскрывает лишнее

Справочник, собранный по всему репозиторию, может включить внутренние модули и служебные комментарии. Явно ограничьте область публикации публичным интерфейсом и проверьте итоговый сайт, а не только настройки генератора. Не полагайтесь на то, что внутренний код «вряд ли кто-то найдёт».

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

Если основной продукт — библиотека, начните со справочника публичного интерфейса и отдельно поддерживайте руководство с примерами. Если команда поддерживает HTTP API, источником описания контрактов должна быть схема, которую сверяют с реальным поведением сервера. Если проекту нужны и инструкции, и API-справочник, соберите их в одном сайте, но не смешивайте источники: генератор справки не должен становиться местом ручного редактирования текста.

В проектах на GitHub удобна проверка документации при каждом PR и публикация после принятого изменения. На другой платформе Git используйте тот же принцип: сначала сборка и проверки, затем публикация. Для конкретной конфигурации пайплайна обращайтесь к документации CI-системы и выбранного генератора: синтаксис и доступные проверки меняются между версиями.

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

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