Как приложить документацию к GitHub Release одним файлом

Упакуйте документацию к конкретной версии программы в один автономный HTML-файл, проверьте его офлайн и приложите к соответствующему GitHub Release.

Зачем делать документацию артефактом выпуска

Ссылка на актуальную документацию полезна активным пользователям, но не всегда правильно описывает старую сборку. Настройки, скриншоты, API и требования изменяются. Человеку, который скачивает предыдущую версию через несколько месяцев, нужно соответствующее ей руководство, а не текущий сайт.

Вложение документации в GitHub Release создает версионированный артефакт рядом с архивом исходного кода и файлами продукта. Один HTML удобнее скачивать, чем папку сгенерированного сайта, и приятнее читать, чем набор Markdown-файлов. В нем остаются логические страницы, навигация, поиск, код и изображения.

Подготовьте документацию для конкретной версии

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

Укажите версию продукта внутри документа и в имени файла, например acme-tool-docs-2.4.1.html. Общее имя documentation.html становится неоднозначным после нескольких скачиваний. Для отдельных языковых файлов добавьте язык в имя.

Соберите один автономный HTML-файл

Markdown-документацию можно продолжать хранить рядом с кодом, преобразуя только результат для передачи. Для публичного репозитория используйте сценарий импорта Markdown из GitHub. Руководства Word и PDF также можно импортировать как основу либо написать страницы непосредственно в One File Docs.

Организуйте материал в понятное читателю дерево и экспортируйте его. One File Docs включает содержимое страниц, навигацию, поиск, код просмотрщика, стили и импортированные изображения в один HTML-файл. Удаленные шрифты, видео, аналитика, внешние скрипты и другие ресурсы по URL остаются сетевыми зависимостями.

Проверьте именно тот файл, который будет загружен

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

Не пересобирайте документ после одобрения без повторной проверки. Проверенный и загруженный файлы должны совпадать. В более строгом процессе выпуска сохраните контрольную сумму вместе с другими артефактами.

  • В документе и программе указана одинаковая версия.
  • Имя файла содержит продукт, версию и при необходимости язык.
  • Установка и быстрый старт работают в чистой среде.
  • Все необходимые страницы, изображения и примеры присутствуют.
  • Офлайн-поведение и оставшиеся сетевые зависимости известны.