Понедельник, 08.09.2025 19:00

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

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

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_examples_doxygen_cmake\ .\colorconsolelib\

Настройка проекта CMake для создания документации для примеров

Откроем наш проект:

cd c:\projects\colorconsolelib
code .

Добавим в конец файла doxygen_settings.cmake.in строки:

# Добавляем папки с документацией для примеров кода использования библиотеки   
set("DOXYGEN_DOC_EXAMPLE_PATH" "../../examples")

# Путь к изображениям для документации
set("DOXYGEN_DOC_IMAGE_PATH" "../../docs/images")

Добавим в конец файла doxyfile.in строки:

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

# Путь к изображениям используемых в документации
IMAGE_PATH = "${DOXYGEN_DOC_IMAGE_PATH}"

В файле \include\colorconsole\colorconsole.h между:

#include <windows.h>

и:

namespace ccon

Добавим:

// Описание примеров для документации
 
/**
* @example basic/main.cpp
* Программа выводит строку каждая буква которой выделена случайным
* цветом текста и фона.
* @image html example_base.png
*
*/

/**
* @example color_table/main.cpp
* Программа таблицу со всеми поддерживаемыми цветами текста и фона
* @image html example_color_table.png
*
*/

/**
* @example Russia_flag/main.cpp
* Программа выводит флаг России
* @image html example_base_rus_flag.png
*
*/


/**
 * @brief Пространство имен  ccon (ColorConsole)
 * 
 */

Обновим файл

\examples\basic\main.cpp
/**
 * @file main.cpp
 * @author Василий Алтунин (skyr@altuninvv.ru)
 * @brief Файл содержит пример использования класса  ColorConsole
 * @version 0.1.0
 * @date 2025-09-05
 *
 * @copyright Алтунин Василий 2025
 *
 * Выводит в консоль строку ColorConsole каждая буква которой,
 * выделена случайным цветом текста и фона
 *
 */

#include <iostream>
#include <string>
#include <random>

#include "../../include/colorconsole/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
    ColorConsole::init(); // Инициализация

    // Настраиваем генератор случайных чисел
    std::random_device rd;
    std::mt19937 gen(rd());
    std::uniform_int_distribution<> distr(0, 15);

    std::string str = "ColorConsole";

    // В цикле выводим каждую букву
    for (int i = 0; i <= str.length() - 1; i++)
    {
       //Устанавливаем случайный цвет текста и фона
        ColorConsole::setConsStdOutColor(distr(gen), distr(gen));
       
        std::cout << str[i];
    }

    //Возвращаем настройки текста по умолчанию
    ColorConsole::setConsStdOutDefColor();

    return 0;
}

Обновим файл

\examples\color_table\main.cpp
/**
 * @file main.cpp
 * @author Василий Алтунин (skyr@altuninvv.ru)
 * @brief Файл содержит пример использования класса ColorConsole
 * @version 0.1.0
 * @date 2025-09-05
 *
 * @copyright Алтунин Василий 2025
 *
 * Выводит в консоль таблицу из всех поддерживаемых цветов 
 * текста и фона 
 *
 */

#include <iostream>

#include "../../include/colorconsole/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
    ColorConsole::init();  // Инициализация

    ColorConsole::emptyLine();  // Новая строка  цветом фона консоли

    for (int i = 0; i < 256; i++) // В цикле проходим по всем 256 цветам

    {
        if ((i % 16 == 0) && (i != 0)) { // После каждого 16 столбца новая строка

            ColorConsole::emptyLine();
        }

        ColorConsole::setConsStdOutColor(i); //Устанавливаем цвет
       
        printf("[%03d]",i); // Выводим номер цвета
    }

    ColorConsole::emptyLine(); // Новая строка  цветом фона консоли

    //Возвращаем настройки текста по умолчанию
    ColorConsole::setConsStdOutDefColor();

    return 0;
}

Обновим файл:

\examples\Russia_flag\main.cpp
/**
 * @file main.cpp
 * @author Василий Алтунин (skyr@altuninvv.ru)
 * @brief Файл содержит пример использования класса ColorConsole
 * @version 0.1.0
 * @date 2025-09-05
 *
 * @copyright Алтунин Василий 2025
 *
 * Выводит в консоль флаг России
 *
 */

#include <iostream>

#include "../../include/colorconsole/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
   ColorConsole::init(); // Инициализация

    // Две новых строки образуют пустую строку 
   ColorConsole::emptyLine();
   ColorConsole::emptyLine();

   // Белый фон и текст
  ColorConsole::setConsStdOutColor(ColorConsole::WHITE,ColorConsole::WHITE);
   printf("%10s"," "); //Выводим 10 пробелов

  ColorConsole::emptyLine(); // Новая строка  цветом фона консоли

   // Белый текст и синий фон
  ColorConsole::setConsStdOutColor(ColorConsole::WHITE,ColorConsole::DARK_BLUE); 
   printf("%10s","  RUSSIA ");

   ColorConsole::emptyLine(); // Новая строка  цветом фона консоли

   // Красный фон и текст
  ColorConsole::setConsStdOutColor(ColorConsole::DARK_RED,ColorConsole::DARK_RED); 
   printf("%10s"," ");

   // Две новых строки образуют пустую строку 
   ColorConsole::emptyLine(); 
  ColorConsole::emptyLine();

   //Возвращаем настройки текста по умолчанию
   ColorConsole::setConsStdOutDefColor();

   return 0;
}

Добавляем картинки к документации

mkdir docs\images

Картинки для документации вы можете загрузить из браузера с помощью - Сохранить как…  и скопировать в папку для изображений, переименовав файлы:

example_base.png

Изображение удалено.

example_color_table.png

Изображение удалено.

example_base_rus_flag.png

Изображение удалено.

 Запустим сборку документации:

cmake --build build --target docs

Откроем созданную документацию.

В панели слева, в самом низу появился раздел:

Примеры

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

Изображение удалено.

Обновляем файл Readme.md

Обязательно обновим главную страницу документации нашей библиотеки. Обновим файл 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)
   - [3.3. Сборка документации](#33-сборка-документации)
   - [3.4. Сборка примеров](#34-сборка-примеров)
- [4. Как использовать библиотеку](#4-как-использовать-библиотеку)
   - [4.1. Использование](#41-использование)
   - [4.2. Версии библиотеки](#42-версии-библиотеки)
      - [4.2.1. Совместимость](#421-совместимость)
   - [4.3. Примеры использования](#43-примеры-использования)
- [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
   ```

## 3.3. Сборка документации
Для сборки документации, после выполнения конфигурирования запустите:
```shell
cmake --build build --target docs
```

## 3.4. Сборка примеров
Для сборки примеров, после выполнения конфигурирования запустите:
```shell
cmake --build build --target examples
```

# 4. Как использовать библиотеку
## 4.1. Использование
_Примеры использования_
Пожалуйста обратитесь к документации класса `ccon::ColorConsole`.
## 4.2. Версии библиотеки
### 4.2.1. Совместимость
Проблем с совместимостью не обнаружено.

## 4.3. Примеры использования
Код с примерами использования библиотеки вы найдете в папке `examples`
# 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

Заключение

Сегодня мы рассмотрели добавление в документацию библиотеки С++ примеров использования кода:

Добавили пути к примерам и изображениям в конфигурацию проекта CMake;

Добавили к файлу \include\colorconsole\colorconsole.h комментарий с описанием примеров, которые нужно добавить в документацию;

Обновили наши примеры, добавив к ним комментарии Doxygen;

В папку для картинок загрузили изображения для документации;

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

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

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

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

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

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

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