main_ubi_sdk v 0.1.3
This is UBI4 documentation
Доработка данной документации

TLDR (too long, didn't read)

Для генерации этой доки используется Doxygen с использованием Graphviz и стилей Doxygen Awesome, по этим ключевым словам можно найти много информации о том, как красиво оформить документацию.

Процесс формирования документации

Данная документация формируется на основе комментариев внутри sdk с помощью утлиты Doxygen и Graphviz для отрисовки графов. Таким образом вся исходная инофрмация документации хранится внутри репозитория main_ubi_sdk, а когда содержимое меняется, оно проходит через генератор, который выдает html файлы в соответствии с настройками в файле ./.doxygen/Doxyfile.

Как улучшить документацию

Доработать документацию можно следующим образом.

  1. Спуллить проект sdk.
  2. Спуллить проект документации в ту же дериикторию (будет удобннее потом запушить).
  3. Изменить doxygen комментарии в репозитори sdk.
  4. Сгенерировать новую документацю с помощью Doxygen приложения (его установка будет дальше). Документация будет сгенерирована в соседнюю папку main_ubi_sdk_docs, которую ты спулил в пункте 2
  5. Открыть документацию локально в браузере и проверить, что все отображается именно так, как ты хочешь (и ничего не сломалось).
  6. Запушить проект документации обратно в gitea
  7. Web версия обновится автоматически в течение пяти минут

Установка и работа с Doxygen и Grapghviz

Устанавливаем Doxygen

  • Windows
    1. Скачать установщик и устновить
    2. По идее переменная PATH должна добавиться сама, но если нет, то добавить руками.
      Должно быть (ну или другое место установки) "C:\Program Files\doxygen\bin"
  • Linux Не проверял
    1. apt install doxygen
    2. cd (Doxyfile dir)
    3. doxygen
  • MacOS Сделать

Устанавливаем GraphViz

  • Windows
    1. Скачать установщик и устновить
    2. При установке проверить, что путь добавлен в PATH. Если нет, то добавить руками.
      Должно быть (ну или другое место установки) "C:\Program Files\Graphviz\bin"
  • Linux Не проверял
    1. apt install doxygen
    2. cd (Doxyfile dir)
    3. doxygen
  • MacOS Сделать

Генерируем файлы и смотрим их

  • Windows
    1. Открыть устновленный Doxywizard
    2. Открыть в Doxywizard файл ./doxygen/Doxyfile в репозитории sdk
    3. Перейти во вкладку Run и выполнить Run doxygen
    4. Посмотреть результат в Show HTML output.
      При повторной генерации заново открывать Show HTML output не нужно, можно просто нажать f5 в браузере
      Attention
      Иногда может появиться желание изменить конфигурацию генератора. Это можно сделать как через GUI, так и напрямую редактируя Doxyfile. Генератору не будет разницы, GUI на самом деле редактирует тот же файл
  • Linux Не проверял
    1. apt install doxygen
    2. cd (Doxyfile dir)
    3. doxygen
  • MacOS Сделать

Использование Doxygen Awesome

Если попробовать сгенерировать голый проект Doxygen, он будет выглядеть куда менее красиво. За это отвечает Doxygen Awesome Например красивые вкладки выше сделаны именно благодаря ему. Как и весь стиль. Все это уже настроено, но если хочется прикрутить еще свистелок, то про это можно почитать по ссылке.