Часть 3, где ваше чудовищное творение достигает мира.

Вы можете найти полный код здесь.

Это последняя глава в этой серии из 3 частей о документации для C++ библиотек в теме ReadTheDocs, размещенной на GitHub. Финальный сайт здесь.

1. Первая часть. Получение некоторых предупреждений об отсутствии документации в процессе сборки. Это будет сделано путем включения Doxygen в CMake.

2. Вторая часть. Создание и запуск действительно хорошего (ReadTheDocs) веб-сайта. Это будет сделано с использованием конвейера Doxygen/Sphinx/Breathe. Я не буду пытаться включить этот шаг в файл CMake — в любом случае это обычно делается через GitHub actions.

3. [Эта часть] Получение GitHub actions для автоматического создания и размещения нашей документации для нас.

Давай закончим это.

Действия GitHub для автоматического развертывания вашего веб-сайта

Эта заключительная часть будет посвящена действиям GitHub для автоматического развертывания вашего веб-сайта. См. предыдущую часть, чтобы сначала настроить конвейер Doxygen/Sphinx/Breathe.

Полученный веб-сайт будет общедоступным в Интернете, даже если проект является частным. Это ограничение GitHub. Если вы хотите, вы можете вместо этого использовать GitLab, который позволяет вам размещать защищенный паролем частный веб-сайт для документирования вашего личного репозитория, что довольно круто!

Гит

Если вы еще этого не сделали, инициализируйте репозиторий git для своего проекта:

git init .

Хороший .gitignore будет:

.vscode/
.DS_Store
build/
_build/
_static/
_templates/

С ними я смог сделать наш игрушечный проект просто

git add .
git commit -m “Initial commit”

Очевидно, нам нужен репозиторий GitHub, так что давайте и создайте его. Я позвонил своему cpp_doxygen_sphinx (сюрприз). См. примечание выше, если вы делаете это частным репо.

Используйте инструкции на веб-сайте репозитория, чтобы отправить первоначальную фиксацию на GitHub.

Действия на GitHub

GitHub Actions причудливы, потому что у нас есть большой рынок предопределенных действий, которые мы можем использовать, поэтому нам не нужно слишком много с ними играть.

GitHub Actions являются **не** причудливыми, потому что нет хорошего способа проверить свои действия офлайн (кроме здесь, но это немного неудобно, особенно потому, что изображения будут огромными). Однако вы можете отлаживать их во время работы, используя отличное действие mxschmitt/action-tmate@v2 — подробнее об этом ниже.

Мы собираемся использовать это замечательное действие Deploy to GitHub Pages. Идите вперед и перейдите туда, нажмите использовать последние. Вы можете увидеть фрагмент, который мы будем использовать.

Чтобы настроить это, перейдите в наш основной каталог и создайте два новых каталога.

mkdir .github
mkdir .github/workflows

Все рабочие процессы будут жить здесь.

Создайте рабочий процесс для создания нашей документации — это должен быть новый файл .github/workflows/docs.yml.

Откройте docs.yml и отредактируйте его так, чтобы он читался

Разбивая это:

  • Действие запускается при нажатии на основную ветку. Как правило, вы все равно должны отправлять большинство коммитов в другие ветки, поэтому это действие должно выполняться только изредка, когда обновляется основная ветка кода. Эти закомментированные строки можно использовать для отключения действия.
  • Requirements: Что-то предустановлено на образ, что-то нет. К счастью, brew и pip есть, но doxygen и sphinx и тому подобное — ну вы сами по себе! Полный список предустановленного ПО находится здесь. Обратите внимание, что мы использовали pip3 вместо python3.
  • Checkout repo: Важный шаг. Раньше это не требовалось, но теперь это (*вздох*), так что будьте осторожны!
  • Build docs: Это строит документы так же, как и раньше, с одним очень важным дополнением:

Страницы GitHub используют Jekyll для создания своих веб-сайтов, который игнорирует каталоги, начинающиеся с _. Это проблема, потому что многие файлы, которые нам нужны, например файлы .js и .css, находятся в папке _static. Простой обходной путь — полностью отключить Jekyll с помощью строк:

…
&& cd _build/html
&& touch .nojekyll

чему я научился здесь (как всегда, ответы на все жизненные вопросы можно найти на stack overflow!).

  • Deploy: Это развертывает папку docs_sphinx/_build/html.

Добавьте его в репозиторий `git` и нажмите:

git add .github
git commit -m “Docs”
git push

Проверить онлайн

Проверьте онлайн на своей GitHub странице под Actions вверху. Вы должны увидеть, что последнее действие Docs запущено (или завершено). Вы можете проверить выходные журналы каждого шага и увидеть, где произошел сбой. Если он выдает какие-то ошибки, см. следующий раздел для отладки действий.

Если все сработало, теперь у вас должна быть красивая страница на GitHub! Вы заметите, что появилась новая ветвь под названием gh-pages. Эта ветка будет выглядеть совсем иначе — это будут просто страницы сайта.

Вы можете найти свой веб-сайт в Интернете по адресу:

https://username.github.io/project-name/

Обратите внимание, что project-name чувствителен к регистру,

Если он не отображается, попробуйте перейти к настройкам на GitHub и включить/выключить страницы (выберите другую ветку, например master, а затем вернитесь к gh-pages).

Ниже мой.

Отладка вашего действия

Вы можете попробовать использовать здесь для небольшой отладки действий, но это, как правило, головная боль, и, вероятно, будет проще просто отредактировать и нажать.

Вы можете отладить свое действие с помощью tmate, используя следующее действие mxschmitt/action-tmate@v2 — создайте новое действие с именем .github/workflows/ssh.yml с содержимым:

После фиксации и отправки вы можете перейти на страницу действий на GitHub и увидеть адрес `ssh` вашей среды. Вы можете ssh использовать терминал и получить живой способ настройки и создания своего действия. Убедитесь, что вы отменили действие в какой-то момент, иначе оно будет выполняться вечно.

Обратите внимание, что вы можете отключить свои действия, изменив их на

push:
  branches-ignore:
    - ‘**’

Чтобы сэкономить время на установку пререквизитов, вы можете попробовать использовать артефакты GitHub.

Последние мысли

Что ж, я надеялся, что вам понравился этот урок из трех частей.

Я, конечно, нет: документация и без того отстойная, да и модулей слишком много, но вот.

Но, по крайней мере, это выглядит причудливо, вроде как.