Всем привет! В этой статье расскажу, как я создаю и публикую документацию для своих проектов. Документация создается автоматически из папки с проектом, развертывается на GitHub и обновляется автоматически при каждом коммите. Готовый результат, чтобы вы поняли нужно ли вам читать дальше, доступен здесь.
Я очень люблю писать код. И вот насколько я люблю писать его, настолько же я не люблю писать документацию, но при этом осознаю всю её важность. Можно писать всю сопроводительную информацию прямо в коде, и написание комментариев является хорошим тоном, так как позволяет проще разобраться в структуре программы или библиотеки. Описание функций или классов прямо в файлах проекта удобно, когда программист видит исходники перед собой и работает непосредственно с ним, но если кто‑то хочет использовать код как черный ящик, и ему мало важны исходники, так как он пользуется, например, готовыми бинарными файлами. В такой ситуации искать необходимые файлы, например, заголовочные для C++, по разным папкам компьютера не очень удобно, и хотелось бы иметь полноценную документацию в одном месте.
Пожалуй, самым популярным типом документации являются сайты на HTML. Однако процесс ручного ведения документации не очень прост, так как необходимо постоянно следить за соответствием между сайтом и проектом, и поэтому были созданы программные методы для извлечения всех данных о классах, функциях и их параметрах, перегрузках и шаблонах. Поскольку информация о всех сущностях проекта извлекается из кода, то в нем же можно и размещать все или почти все описание.
Doxygen
Doxygen — это система автоматического документирования. Он поддерживает множество разных типов выходной документации, например HTML и man-файлы, но в статье будет информация только об HTML. Doxygen обрабатывает код, достает из него всё, что указано в настройках, например классы и их методы, добавляет информацию об этих методах в документацию, а затем вставляет описание из комментариев из исходников в доки.
Но каким образом он понимает, какой текст нужно извлекать? Для этого все комментарии должны быть написаны в определенном формате. Я не буду углубляться в этот формат, так как на «Хабре» есть отличный цикл статей, посвященный всей системе. Важно сказать, что Doxygen поддерживает markdown внутри комментариев, что очень удобно.
Установка Doxygen
Это необязательный шаг, так как документация будет верстаться в облаке, но для ее проверки и отладки удобно иметь возможность верстать ее локально. Для использования всех функций системы дополнительно потребуется Graphviz. Он нужен для создания картинок.
Windows
Перейдите на страничку загрузки.
Скачайте инсталлятор или архив с бинарными файлами.
Страница загрузки Doxygen Запустите инсталлятор и установите программу. Обязательно запомните путь установки. Вам потребуется папка bin. По умолчанию это - «C:\Program Files\doxygen\bin».
Если вы решили скачать zip-архив, то достаточно просто запомнить путь к разархивированной папке.
Так как, зачастую, генерация документации вызывается через скрипт, то нужно добавить Doxygen в path. Для этого туда надо добавить папку с бинарниками. Чтобы сделать это найдите в системном поиске «Изменение системных переменных среды»
Изменение системных переменных среды В появившемся окне откройте пункт «Переменные среды»
Переменные среды В системных переменных откройте пункт «Path»
Path Добавьте путь к папке bin, которая находится в папке установки Doxygen.
Если вы выбрали zip-архив, то добавить нужно путь к папке bin, которая расположена внутри распакованного архива.
Doxygen в Path`е Перейдите на страницу установки Graphviz и скачайте удобную для вас версию.
Запустите инсталлятор и на этапе «Install Options» выберете 2 пункт «Add Graphviz to the system PATH for all users».
Add Graphviz to the system PATH for all users
На этом установка всего необходимого завершена
Linux
Для Ubuntu
sudo apt install doxygen graphviz
Для Arch
sudo pacman -S doxygen graphviz
Для демонстрации документации я создам один файлик, в котором будут находится самые важные и часто встречаемые конструкции, которые обычно документируются.
Документирование
Так как для документации совершенно неважно, как внутри работает логика, я создам один заголовочный файл и задокументирую его.
Для начала выполните:doxygen -g для создания конфигурационного файла по умолчанию. Вместе с Doxygen поставляется doxywizard, который предоставляет графический интерфейс для изменения конфигурационного файла, но файла настроек в этой статье я почти не буду касаться, поэтому и использовать его не буду.
Создадим класс Math для математических операций.
/**
\brief Класс для математических операций.
Данный класс предоставляет функционал разных математических операций для шаблоных типов.
*/
class Math {};
С помощью brief объявляется краткое описание, а всё что идет ниже будет являться полным описанием.
Для генерации документации вызовите команду doxygen в папке с кодом. Посмотрим на сгенерированную документацию:
Добавим в класс функцию Summ. Чтобы doxygen извлек функцию, она должна находиться в секции public или protected.
/**
\brief Шаблонная функция суммирования двух объектов
\tparam T - любой тип, для которого определен оператор суммирования
и оператор присваивания
\param [in] a Первый объект, который нужно сложить
\param [in] b Второй объект, который нужно сложить
\return Новый объект типа *T*, равный сумме *a* и *b*.
*/
template <class T>
T Summ(const T& a, const T& b);С помощью команды tparam указывается информация о шаблонных типах.
С помощью param указывается информация о входном значении. Эта команда имеет дополнительный параметр, указывающий направление переменной. Прочитать про это можно тут.
С помощью return указывается информация о возвращаемом значении.
Теперь в доки:
Добавим еще одну функцию. Пускай это будет функция извлечения корня.
/**
\brief Шаблонная функция извлечения корня из объекта
\tparam T - любой тип, из которого можно извлечь корень
\param [in] a Объект для извлечения корня
\return Новый объект типа *T*, равный корню *a*.
\code{cpp}
Math m;
double d = m.Sqrt(2.542);
\endcode
\warning Не принимает отрицательные значения
*/
template <class T>
T Sqrt(const T& a);Первая часть описания функции была разобрана у предыдущей функции, поэтому приступим к новому.
Команда code нужна для размещения кода в документации. Это может быть удобно, например, для демонстрации вызова функции.
С помощью warning можно помечать важную информацию так, чтобы ее было сложно пропустить.
Отлично, теперь у нас есть HTML документация, которая создается из исходного кода и для этого надо вызвать всего одну команду.
Doxygen Awesome
Доки получились хорошими, но не очень красивыми. Исправить это можно с помощью стилей, например, этого. Он достаточно красив и обычно я использую именно его.
Для его установки скачайте последний релиз с GitHub и разместите в папке с проектом. Если вы не хотите засорять свой проект ненужными файлами, то можете написать скрипт для автоматического клонирования стилей и верстания документации. Так как главным является стиль, то я предпочитаю брать только его и хранить прямо в проекте.
Для подключения стиля необходимо добавить его в Doxyfile. Для этого необходимо присвоить параметру «HTML_EXTRA_STYLESHEET» путь к файлу со стилем.
Это можно сделать через текстовый редактор:
Или через doxywizard:
Посмотрим на новый стиль. Вот так выглядит описание класса:
Вот так метод Sqrt:
Ну и последний метод:
Отлично! Теперь документация выглядит красиво и современно.
Github Pages
Для начала создадим репозиторий на GitHub. Откройте главную вкладку репозитория.
Перейдите на вкладку Settings и откройте раздел Pages:
В этом разделе выберете Static HTML и нажмите кнопку Configure.
Откроется файл конфигурации задачи для CI/CD пайплайна. Все настройки хранятся в static.yaml файле. С помощью пайплайна можно вызывать системные команды. Вызов всех команд описывается с помощью шагов. Описание шагов начинается после строки steps. Путь к этой строке: jobs -> deploy -> steps.
Первые два шага по умолчанию выглядят так:
При обновлении GitHub Pages может что-то поменяться, но я не думаю, что будет сложно понять, где надо писать свои шаги.
Теперь требуется добавить шаги с установкой Doxygen. В качестве системы используется Ubuntu, а значит пакеты устанавливаются через apt.
# Install Doxygen
- name: Install Doxygen
run: sudo apt install doxygen && doxygen --version
- name: Install Graphviz
run: sudo apt install graphvizДля создания документации на сервере добавьте шаг, создающий документацию:
# Create documentation
- name: Create documentation
run: doxygenДокументация создается, но надо ее развернуть. Для этого необходимо указать путь к папке с index.html в шаге Upload artifact. По умолчанию этот шаг выглядит так:
Про реальные проекты
Шаг с развертыванием документации
В данной статье генерация документации происходит в корне проекта, однако это не очень удобно в реальных проектах. Удобно генерировать документацию в другой папке, и для развёртывания сайта из этой папки нужно указать путь к папке с index.html на данном шаге.
Путь к главной странице сайта: ./html/index.html. Тогда этот шаг будет выглядеть так:
Закоммитьте новый файл в проект. С помощью вкладки actions можно отслеживать все действия.
Для удобства оставлю полный static.yaml файл.
static.yaml
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v4
# Install Doxygen
- name: Install Doxygen
run: sudo apt install doxygen && doxygen --version
- name: Install Graphviz
run: sudo apt install graphviz
# Create documentation
- name: Create documentation
run: doxygen
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: './html/'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4Теперь осталось только добавить исходный код, Doxyfile и стиль doxygen-awesome.css в репозиторий, а затем закоммитить и отправить на GitHub.
Отслеживать развертывание документации можно с помощью иконки справа от описания последнего коммита.
На этом настройка закончена. Ссылка на документацию находится в раздел Settings -> Pages.
Перейдя по ссылке можно увидеть следующее:
Выглядит не очень, но это легко исправить. Doxygen поддерживает .md файлы. С их помощью можно создавать полноценные HTML-страницы. Добавим в проект ReadMe.md файл и сделаем его главной страницей документации, а заодно и удостоверимся в том, что документация обновится после коммита.
Теперь главная страница проекта выглядит так:
Чтобы страница стала главной в документации, нужно вначале страницы указать \mainpage, однако эта же строка будет отображаться при открытии документа, что может быть неудобно, например, на главной странице проекта на GitHub. Для решения этой проблемы можно написать скрипт, который автоматически во время создания документации добавит эту строчку в начало файла или же можно разделить файл ReadMe.md и главную страницу документации.
Заключение
Так, весьма просто, можно настроить документацию для проекта.
