Среда, 03.09.2025 19:00

Собираем документацию для библиотеки с помощью Doxygen и CMake

Собираем документацию для библиотеки с помощью Doxygen и CMake

Doxygen облегчает создание документации для вашего проекта, но вместе с тем, требует запуска отдельной программы для сборки документации.

В прошлой статье мы рассмотрели создание документации для библиотеки C++ с помощью Doxygen. Сегодня мы добавим настройки для CMake, чтобы облегчить настройку и автоматизировать сборку документации.

Настройка проекта

Начнем мы с проекта, размещенного в git-репозитории. Мы продолжим настройку проекта из прошлой статьи.

Если папка:

c:\project\colorconsolelib

уже существует, переместите или удалите её:

cd c:\projects
rmdir /q/s colorconsolelib

Мы будем использовать проект из git-репозитория:

cd c:\projects
rmdir /q/s articles_blog_altuninvv_ru
git clone https://gitflic.ru/project/vasiliyaltunin/articles_blog_altuninvv_ru.git --depth 1

Скопируем папку с проектом:

xcopy /y/e .\articles_blog_altuninvv_ru\qt6\libcolorconsole_doxygen\colorconsolelib\ .\colorconsolelib\

Создадим файлы:

cd c:\projects\colorconsolelib
type nul > docs\doxyfile.in
type nul > cmake\doxygen_settings.cmake.in

Откроем в VSCode:

code .

В файл cmake\doxygen_settings.cmake.in добавим:

# Кодировка
set("DOXYGEN_DOC_DOXYFILE_ENCODING" "UTF-8")

# Название проекта
set("DOXYGEN_DOC_PROJECT_NAME" "Color Console Library")

# Версия проекта, должна совпадать с версией в файле CMakeFiles.txt
# в строке
# VERSION 0.1.0
set("DOXYGEN_DOC_PROJECT_NUMBER" "0.1.0")

# Краткое описание проекта
set("DOXYGEN_DOC_PROJECT_BRIEF" "С помощью этой библиотеки можно выводить цветной текст в консоль Windows")

# Лого проекта мы не будем использовать логотип
set("DOXYGEN_DOC_PROJECT_LOGO" "")

# Иконка проекта мы не будем использовать её
set("DOXYGEN_DOC_PROJECT_ICON" "")

# Задаем каталог с исходным текстом из которого doxygen будет брать файлы
set("DOXYGEN_DOC_INPUT" "../../ \\ 
                         ../../README.md")

# Указываем какое файлы нужно документировать
set("DOXYGEN_DOC_FILE_PATTERNS" "*.cpp \\
                                 *.h")

# Указываем doxygen автоматически просматривать подкаталоги в поисках файлов
set("DOXYGEN_DOC_RECURSIVE" "YES")

# Указываем doxygen исключить из обработки папки, которые не нужно обрабатывать
# Нам так же не нужно, чтобы внутренние заголовки библиотеки документировались
set("DOXYGEN_DOC_EXCLUDE" "../../cmake \\
                           ../../build \\
                          ../../src/colorconsole.h")

# Как правило мы исключаем все папки с тестами из документации, и хотя тестов у нас 
# пока что нет, мы все равно пропишем не будущее
set("DOXYGEN_DOC_EXCLUDE_PATTERNS" "*/test/*")

# Эта опция указывает использовать файл README.md как главную страницу нашей 
# документации, мы создадим его позже
set("DOXYGEN_DOC_USE_MDFILE_AS_MAINPAGE" "../../README.md")

# Нам не нужен вывод в формате LATEX
set("DOXYGEN_DOC_GENERATE_LATEX" "NO")

# Вырезаем полные пути из документации, в противном случае у нас в документации будут 
# длинные пути к файлам, например:
# /c/projects/colorconsolelib/include/colorconsole/colorconsole.h
set("DOXYGEN_DOC_FULL_PATH_NAMES" "NO")

# Задаем язык нашей документации
set("DOXYGEN_DOC_OUTPUT_LANGUAGE" "Russian")

Здесь мы просто указываем параметры, которые CMake подставит в шаблон, при создании файла конфигурации Doxygen.

В файл docs\doxyfile.in

# Doxyfile 1.14.0

#---------------------------------------------------------------------------
# Настройки проекта
#---------------------------------------------------------------------------

# Кодировка
DOXYFILE_ENCODING     = "${DOXYGEN_DOC_DOXYFILE_ENCODING}"

# Название проекта
PROJECT_NAME           = "${DOXYGEN_DOC_PROJECT_NAME}"

# Версия проекта, должна совпадать с версией в файле CMakeFiles.txt
# в строке
# VERSION 0.1.0
PROJECT_NUMBER        = "${DOXYGEN_DOC_PROJECT_NUMBER}"

# Краткое описание проекта
PROJECT_BRIEF         = "${DOXYGEN_DOC_PROJECT_BRIEF}"

# Лого проекта мы не будем использовать логотип
PROJECT_LOGO          = "${DOXYGEN_DOC_PROJECT_LOGO}"

# Иконка проекта мы не будем использовать её
PROJECT_ICON          = "${DOXYGEN_DOC_PROJECT_ICON}"

# Задаем каталог с исходным текстом из которого doxygen будет брать файлы
INPUT                 = ${DOXYGEN_DOC_INPUT}

# Указываем какие файлы нужно документировать
FILE_PATTERNS         = ${DOXYGEN_DOC_FILE_PATTERNS}

# Указываем doxygen автоматически просматривать подкаталоги в поисках файлов
RECURSIVE             = "${DOXYGEN_DOC_RECURSIVE}"

# Указываем doxygen исключить из обработки папки, которые не нужно обрабатывать
# На так же не нужно, чтобы внутренние заголовки библиотеки документировались
EXCLUDE               = ${DOXYGEN_DOC_EXCLUDE}

# Как правило мы исключаем все папки с тестами из документации, и хотя тестов у нас 
# пока что нет, мы все равно пропишем не будущее
EXCLUDE_PATTERNS      = "${DOXYGEN_DOC_EXCLUDE_PATTERNS}"

# Эта опция указывает использовать файл README.md как главную страницу нашей 
# документации, мы создадим его позже
USE_MDFILE_AS_MAINPAGE = "${DOXYGEN_DOC_USE_MDFILE_AS_MAINPAGE}"

# Нам не нужен вывод в формате LATEX
GENERATE_LATEX        = "${DOXYGEN_DOC_GENERATE_LATEX}"

# Вырезаем полные пути из документации, в противном случае у нас в документации будут 
# длинные пути к файлам, например:
# /c/projects/colorconsolelib/include/colorconsole/colorconsole.h
FULL_PATH_NAMES = "${DOXYGEN_DOC_FULL_PATH_NAMES}"

# Задаем язык нашей документации
OUTPUT_LANGUAGE = "${DOXYGEN_DOC_OUTPUT_LANGUAGE}"

Это просто файл-шаблон, вместо ${DOXYGEN_DOC_ХХХ} CMake подставит значения из файла cmake\doxygen_settings.cmake.in.

В файл targets.cmake.in перед 

message(" === Targets settings complete")

добавим:

# Пытаемся найти Doxygen
find_package(Doxygen)

if(Doxygen_FOUND) # Если Doxygen найден

    # Добавляем target для сборки документации в папке build/docs
    # с использованием автоматически сгенерированным файлом 
    # конфигурации build/docs/Doxyfile
    doxygen_add_docs(docs 
                    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs
                    ALL
                    CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile
                    )

    message(" === Documentation setup complete")
endif()

Здесь мы даем указание CMake найти Doxygen, и если он найден, добавляем новый target - docs. 

В файл libconf.cmake.in:

Перед строкой:

message(" === Libconf settings complete")

Добавим:

# Подключаем файл с настройками Doxygen
include(${PROJECT_SOURCE_DIR}/cmake/doxygen_settings.cmake.in)

# Создаем файл Doxyfile на базе шаблона
configure_file(docs/doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile)

message(" === Doxygen config generated")

Здесь мы включаем файл с настройками в основную конфигурацию и создаем файл Doxyfile на базе шаблона docs/doxyfile.in.

Удалим папку build:

cd c:\projects\colorconsolelib
rmdir /s/q .\build\

Запустим конфигурирование:

cmake -S . -B build

Запустим сборку:

cmake --build build
[ 66%] Built target colorconsole
[100%] Generate API documentation for colorconsole_docs
Doxygen version used: 1.14.0
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for msc files...
Searching for dia files...
…
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
type lookup cache used 0/65536 hits=0 misses=0
symbol lookup cache used 0/65536 hits=0 misses=0
finished...
[100%] Built target colorconsole_docs

Вывод обрезан.

В папке build\docs\html\ будет сгенерирована наша документация.

Собираем внутреннюю и внешнюю документацию

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

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

Для реализации этого механизма мы создадим опцию BUILD_EXTERNAL_DOCS, которая по умолчанию у нас установлена и включена. Поэтому по умолчанию у нас собирается внешняя версия документации.

Откроем файл cmake\doxygen_settings.cmake.in и заменим содержимое на:

# Сборка внешней документации для пользователей
# По умолчанию ON
option(BUILD_EXTERNAL_DOCS "Build external library docs" ON)

# Кодировка
set("DOXYGEN_DOC_DOXYFILE_ENCODING" "UTF-8")

# Название проекта
set("DOXYGEN_DOC_PROJECT_NAME" "Color Console Library")

# Версия проекта, должна совпадать с версией в файле CMakeFiles.txt
# в строке
# VERSION 0.1.0
set("DOXYGEN_DOC_PROJECT_NUMBER" "0.1.0")

# Краткое описание проекта
set("DOXYGEN_DOC_PROJECT_BRIEF" "С помощью этой библиотеки можно выводить цветной текст в консоль Windows")

# Лого проекта мы не будем использовать логотип
set("DOXYGEN_DOC_PROJECT_LOGO" "")

# Иконка проекта мы не будем использовать её
set("DOXYGEN_DOC_PROJECT_ICON" "")

# Указываем doxygen автоматически просматривать подкаталоги в поисках файлов
set("DOXYGEN_DOC_RECURSIVE" "YES")

# Как правило мы исключаем все папки с тестами из документации, и хотя тестов у нас 
# пока что нет, мы все равно пропишем не будущее
set("DOXYGEN_DOC_EXCLUDE_PATTERNS" "*/test/* \\
                                    ../../cmake \\
                                   ../../build")

# Эта опция указывает использовать файл README.md как главную страницу нашей 
# документации, мы создадим его позже
set("DOXYGEN_DOC_USE_MDFILE_AS_MAINPAGE" "../../README.md")

# Нам не нужен вывод в формате LATEX
set("DOXYGEN_DOC_GENERATE_LATEX" "NO")

# Вырезаем полные пути из документации, в противном случае у нас в документации будут 
# длинные пути к файлам, например:
# /c/projects/colorconsolelib/include/colorconsole/colorconsole.h
set("DOXYGEN_DOC_FULL_PATH_NAMES" "NO")

# Задаем язык нашей документации
set("DOXYGEN_DOC_OUTPUT_LANGUAGE" "Russian")



# Указываем какие файлы нужно документировать
if (BUILD_EXTERNAL_DOCS STREQUAL "OFF")
# Задаем каталог с исходным текстом из которого doxygen будет брать файлы
    # Если собираем внутреннюю документацию, то обрабатываем все файлы 
    set("DOXYGEN_DOC_INPUT" "../../src \\ 
                             ../../include \\ 
                            ../../README.md")
    set("DOXYGEN_DOC_FILE_PATTERNS" "*.cpp \\
                                    *.h")                                     
    message(" === Building INTERNAL docs")
else()
    # Если собираем документацию для пользователей, то обрабатываем 
    # только файлы *.h из папки /include
    # Задаем каталог с исходным текстом из которого doxygen будет брать файлы
    set("DOXYGEN_DOC_INPUT" "../../include/ \\ 
                         ../../README.md")

    # Обрабатываем только файлы с расширением .h
    set("DOXYGEN_DOC_FILE_PATTERNS" "*.h")
   
    # Отключаем EXCLUDE, чтобы сканировались только папки и 
    # файлы указанные в INPUT 
    set("DOXYGEN_DOC_EXCLUDE" "")

    message(" === Building EXTERNAL docs")
endif()

Здесь мы просто проверяем значение, в которое установлена опция BUILD_EXTERNAL_DOCS.

Для внутренней документации мы сканируем папки .\include и .\src, для внешней только папку .\include.

Теперь для сборки внешней документации можно запустить:

cmake -S . -B build

Или использовать опцию

cmake -S . -B build -DBUILD_EXTERNAL_DOCS=ON

Для сборки внутренней документации нужно запускать:

cmake -S . -B build -DBUILD_EXTERNAL_DOCS=OFF

Отключаем автоматическую сборку документации

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

Заменим содержимое файла targets.cmake.in на:

# Добавляем файлы с исходным кодом к нашему проекту
target_sources(${PROJECT_NAME} PRIVATE ${sources})

# Добавляем папку src к нашему проекту
target_include_directories(${PROJECT_NAME}
    PRIVATE
      "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>"
)

# Если библиотека используется как папка, открываем доступ к заголовочным файлам
target_include_directories(${PROJECT_NAME}
    PUBLIC 
       "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
)


# Имя файла библиотеки. К нему автоматически будет добавлено lib
set_target_properties(${PROJECT_NAME} PROPERTIES OUTPUT_NAME "${MY_LIB_OUTPUT_NAME}")


find_package(Doxygen)

if(Doxygen_FOUND)

    doxygen_add_docs(docs 
                    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs
                    ALL
                    CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile
                    )

    # Имя файла библиотеки. К нему автоматически будет добавлено lib
    set_target_properties(docs PROPERTIES EXCLUDE_FROM_ALL TRUE)

  message(" === Documentation setup complete")
endif()



message(" === Targets settings complete")

Здесь мы для docs устанавливаем опцию:

    set_target_properties(docs PROPERTIES EXCLUDE_FROM_ALL TRUE)

Она исключает данный target из сборки по умолчанию.

Удалим папку build и запустим конфигурирование и сборку:

cd c:\projects\colorconsolelib
rmdir /s/q .\build\
cmake -S . -B build
cmake --build build
[2/2] Linking CXX shared library libcolorconsole.dll

На этот раз произошла только сборка проекта.

Чтобы запустить сборку документации нам теперь при сборке нужно добавить параметр --target.

Запустим:

cmake --build build --target docs
 [1/1] Generate API documentation for docs
…
Generating file member index...
Generating example index...
finalizing index lists...
writing tag file...
Running plantuml with JAVA...
type lookup cache used 7/65536 hits=0 misses=7
symbol lookup cache used 27/65536 hits=260 misses=27
finished...

Будет запущена только сборка документации.

Теперь, всё что нам осталось - это обновить файл README.md:

**ColorConsole** библиотека позволяющая выводить цветной текст в консоль.
**Содержание :**
- [1. Описание библиотеки](#1-описание-библиотеки)
 - [1.1. Возможности](#11-возможности)
 - [1.2. Поддерживаемые платформы](#12-поддерживаемые-платформы)
   - [1.2.1. Статус поддержки](#121-статус-поддержки)
- [2. Требования](#2-требования)
 - [2.1. Стандарты C++](#21-стандарты-c)
 - [2.2. Зависимости](#22-зависимости)
- [3. Как собрать библиотеку](#3-как-собрать-библиотеку)
 - [3.1. Использование CMake](#31-использование-cmake)
 - [3.1.1. Встраиваемая библиотека](#311-встраиваемая-библиотека)
 - [3.1.1. Статическая и разделяемая библиотеки](#311-статическая-и-разделяемая-библиотеки)
 - [3.2. Опции CMake](#32-опции-cmake)
- [4. Как использовать библиотеку](#4-как-использовать-библиотеку)
 - [4.1. Использование](#41-использование)
 - [4.2. Версии библиотеки](#42-версии-библиотеки)
   - [4.2.1. Совместимость](#421-совместимость)
- [5. Документация](#5-документация)
- [6. Лицензия](#6-лицензия)

# 1. Описание библиотеки
## 1.1. Возможности
- Вывод цветного текста в консоль Windows
- Изменение фона текста
- Сброс фона до настроек по умолчанию
## 1.2. Поддерживаемые платформы
### 1.2.1. Статус поддержки
- Windows - поддерживается Windows 10
- Linux - в настоящий момент не поддерживается
# 2. Требования
## 2.1. Стандарты C++
Библиотека поддерживает стандарт **C++ 17** и выше
## 2.2. Зависимости
У проекта нет внешних зависимостей.
Библиотека собирается с использованием MSYS2 и компилятора GCC.
# 3. Как собрать библиотеку
## 3.1. Использование CMake
### 3.1.1. Встраиваемая библиотека
Данная библиотека может использоваться в качестве _встраиваемой_ как папка в папке проекта :
В **главный** файл CMakeLists.txtl добавьте :
```cmake
# Если вы разместили библиотеку в папке lib: add_subdirectory(lib/colorconsole)
add_subdirectory(colorconsole) 
```
### 3.1.1. Статическая и разделяемая библиотеки
Данная библиотека может собираться с внешним проектом в качестве статической или разделяемой:
В **главный** файл CMakeLists.txtl добавьте :
```cmake
# ON - для сборки разделяемой, OFF - для сборки статической
option(BUILD_SHARED_LIBS "Build using shared libraries" OFF)
```

```cmake
target_link_libraries(${PROJECT_NAME} PRIVATE ccon::colorconsole)
```
## 3.2. Опции CMake
Библиотека предоставляет следующие опции **CMake**:
- BUILD_SHARED_LIBS = ON | OFF
   - ON - собирать как разделяемую библиотеку
   - OFF - собирать как статическую библиотеку
   Использование:
   ```shell
   cmake -S . -B build -DBUILD_SHARED_LIBS=OFF
   ```
- BUILD_EXTERNAL_DOCS = ON | OFF
   - ON - собирать внешнюю документацию
   - OFF - собирать внутреннюю документацию
   Использование:
   ```shell
   cmake -S . -B build -DBUILD_EXTERNAL_DOCS=OFF
   ```
# 4. Как использовать библиотеку
## 4.1. Использование
_Примеры использования_
Пожалуйста обратитесь к документации класса `ccon::ColorConsole`.
## 4.2. Версии библиотеки
### 4.2.1. Совместимость
Проблем с совместимостью не обнаружено.

# 5. Документация
Все классы и функции были задокументированы с помощью Doxygen.

Чтобы собрать документацию запустите:
```shell
cmake --build build --target docs
```
В папке `./build/docs/html/` будет создана документация.
# 6. Лицензия
Эта библиотека лицензирована под [лицензией GPLv3][repo-license-url].
<!-- Ссылки -->
[repo-license-url]: https://www.gnu.org/licenses/gpl-3.0.html

Заключение

Сегодня мы рассмотрели сборку документации, созданной при помощи Doxygen для библиотеки C++ c помощью CMake:

Создали файлы конфигурации CMake для настройки Doxygen;

Внесли изменения в конфигурацию Cmake для запуска сборки документации;

Добавили механизм для сборки внешней и внутренней документации;

Отключили автоматическую сборку документации, при сборке всей библиотеки;

Обновили документацию в файле README.md.

Категория C++
Теги Cpp Doxygen CMAKE

Добавить комментарий

О текстовых форматах

Простой текст

  • HTML-теги не обрабатываются и показываются как обычный текст
  • Строки и абзацы переносятся автоматически.
  • Адреса веб-страниц и email-адреса преобразовываются в ссылки автоматически.
Просмотров: 272