Генерация документации из кода в Git: что выбрать

Если генерировать документацию локально и коммитить результат вместе с кодом, Git быстро наполняется шумными диффами и файлами, которые никто не проверял. Если собирать её только в CI, проще держать исходники документации рядом с проектом, но сборка становится зависимой от версий генератора и окружения. Ниже — сравнение трёх инструментов и критерии, по которым выбрать подход для репозитория.

Сначала определите, что именно генерировать

Под «документацией из кода» часто имеют в виду разные вещи: справочник по публичному API из docstring или комментариев, описание модулей и связей между ними, либо пользовательские инструкции, которые авторы поддерживают вручную. Генератор хорошо справляется с первым и частично со вторым. Он не знает, почему продукт устроен именно так, и не заменит объяснения сценариев использования.

Поэтому рабочая схема обычно смешанная: исходный код поставляет описания API, а команда пишет вручную концепции, примеры и инструкции. В Git хранят и то и другое в исходном виде. Сгенерированные HTML-файлы чаще собирают в CI и публикуют отдельно, а не добавляют в каждый коммит.

Три варианта для разных проектов

Для сравнения возьмём закреплённые ориентиры: Git 2.47.1, Sphinx 8.1.3, MkDocs 1.6.1 и Doxygen 1.12.0. Это конкретные версии для обсуждения поведения и совместимости, а не заявление о последних релизах. Перед внедрением проверьте актуальные требования и совместимость плагинов.

Sphinx: Python-проект с развитой технической документацией

Sphinx подходит, когда исходники Python уже снабжены docstring, а рядом нужны страницы о настройке, архитектуре и сценариях использования. Расширение autodoc получает описания из импортируемых модулей; структура разделов и пояснительный текст остаются в исходниках документации. Результат — единая сборка справочника API и написанных вручную страниц.

Цена такого контроля — окружение сборки. Чтобы прочитать модуль, Sphinx может импортировать его, а импорт способен требовать зависимости или запускать нежелательные действия. В CI нужно установить проект и зависимости в контролируемом окружении; документацию не стоит собирать с боевыми секретами и доступом к рабочим системам. Для проекта, где импорт модулей не изолирован, это может стать отдельной задачей.

MkDocs с mkdocstrings: Markdown и документация рядом с кодом

MkDocs строит сайт из Markdown-страниц. Плагин mkdocstrings умеет формировать API-разделы по исходникам, поэтому автор может держать объяснения и структуру документации в привычном для команды формате. Этот вариант удобен, когда важнее простая навигация по страницам и быстрый вклад разработчиков, чем сложная система перекрёстных ссылок и расширений.

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

Doxygen: комментарии в C и C++ и структурный справочник

Doxygen часто выбирают для C и C++, а также проектов на других поддерживаемых языках, где комментарии к объявлениям — основа API-справки. Он извлекает информацию из исходников и может строить связи между сущностями и графы. Это полезно в библиотеке, где потребителю важны типы, функции и отношения между ними, а не только текстовое описание модулей.

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

Сравнение

Сравнение касается не качества текста, а места каждого инструмента в Git-процессе. Ни один из них не превращает плохо описанный интерфейс в хорошую документацию.

Как встроить генерацию в Git

Для большинства команд практичный вариант — хранить исходники документации и настройки в репозитории, а HTML строить в CI после изменений. Так в pull request можно проверять саму сборку, но не засорять историю коммитами с тысячами перегенерированных файлов.

1. Закрепите окружение. Зафиксируйте версии генератора, плагинов и зависимостей в используемом менеджере пакетов. Проверьте, что CI устанавливает именно их, а не случайную последнюю версию. Если сборка прошла на том же наборе зависимостей, что указан в репозитории, окружение воспроизводимо.
2. Проверяйте генерацию при изменении исходников документации. Настройте CI так, чтобы он собирал справку на изменениях исходного кода и страниц документации. Успешная сборка подтверждает отсутствие ошибок генератора, но не гарантирует, что текст точен и понятен.
3. Публикуйте результат из CI. Выберите существующий в вашем проекте канал публикации: например, артефакт сборки или сайт документации. После публикации откройте несколько ключевых страниц и проверьте ссылки, навигацию и соответствие версии кода.
4. Добавляйте проверку полноты отдельно. Если для проекта важно документировать публичный API, договоритесь, как выявлять недокументированные элементы: правилом линтера, проверкой конфигурации генератора или ревью. Успешная сборка сама по себе не доказывает полноту справочника.

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

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

Когда что выбирать

• Берите Sphinx, если проект написан на Python, нужен API-справочник и документация включает много связанных технических страниц.
• Берите MkDocs с подходящим обработчиком, если команда пишет страницы в Markdown и хочет собирать сайт с API-разделом без отдельного процесса для каждого формата.
• Берите Doxygen, если важны комментарии к объявлениям и структурный справочник по C/C++ или другому поддерживаемому языку.
• Не выбирайте инструмент только по тому, насколько эффектно выглядит демо. Проверьте сборку на реальном модуле с его зависимостями и типичными комментариями.

Термин: артефакт сборки — файл или набор файлов, который CI создаёт из исходников, например готовый сайт документации. Он отличается от исходника тем, что обычно его не редактируют вручную.

Что ломается и как это заметить

Сборка проходит локально, но падает в CI

Чаще всего отличается окружение: версия Python или генератора, доступность зависимости, путь к исходникам. Сравните версии в логах и проверьте, что CI устанавливает зависимости из зафиксированного файла. Не лечите проблему добавлением случайного пакета на сервере: тогда сбой вернётся при следующей сборке.

Страница API пустая или пропала из навигации

Проверьте, что исходный модуль доступен генератору и нужная страница включена в структуру сайта. Для Sphinx отдельно проверьте импортируемость модулей; для MkDocs — настройки страниц и плагина; для Doxygen — правила обработки комментариев и исходных файлов. Точное сообщение зависит от инструмента и конфигурации, поэтому ориентируйтесь на лог конкретной сборки.

Дифф сгенерированных файлов занимает весь pull request

Это признак, что в Git попадает не тот слой. Если команда не обязана хранить готовый HTML, исключите его из обычных коммитов и публикуйте результат через CI. Если обязана, перегенерируйте файлы одной закреплённой версией и не редактируйте выходные HTML вручную.

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

Возьмите один модуль, который часто меняется и имеет внешний API, и соберите для него документацию в CI. Проверьте четыре вещи: сборка повторяется на чистом окружении, изменения исходников видны в pull request, ссылка на результат доступна команде, а публичные элементы не исчезают без объяснения. После этого измеряйте не размер HTML, а время CI, частоту ошибок сборки и число исправлений документации после релиза.

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