Cоздаем документацию для программы C++ с помощью Python Sphinx и CMake
При написании любой программы одним из важных этапов является создание документации или инструкции для пользователя. Данный процесс сам по себе трудозатратен, а если над проектом работает несколько человек, то одним файлов в формате Word обойтись уже не получиться.
В одной из прошлых статей мы рассмотрели создание документации исходного кода для библиотеки С++ с использованием Doxygen и CMake. Сегодня мы создадим документацию для самой программы с использованием Python Sphinx и CMake.
Doxygen больше всего подходит для автоматизированного создания документации именно исходного окна программы. Python Sphinx идеально подходит для создания документации самой программы, так как содержит больше возможностей для её описания и разметки, но при этом может создавать и документацию на программный код.
Настройка проекта
Начнем мы с проекта, размещенного в git-репозитории.
Если папка:
c:\project\colortable_user_docsуже существует, переместите или удалите её:
cd c:\projects
rmdir /q/s colortable_user_docsМы будем использовать проект из 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\colortable_user_docs\ .\colortable_user_docs\Установка Python Sphinx
Для начала установим все необходимые пакеты:
pacman -S mingw-w64-x86_64-python-sphinx mingw-w64-x86_64-python-pipНастройка проекта Python Sphinx
Проверим что всё правильно установилось, для этого создадим и соберем пустой проект Python Sphinx.
Создадим папку:
cd c:\Projects\colortable_user_docs\
mkdir docs
cd docsИнициализируем папку документации:
sphinx-quickstartWelcome to the Sphinx 8.2.3 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:Ответим
yThe project name will occur in several places in the built documentation.
> Project name:Введем
colortable> Author name(s):Введем
Vasiliy Altunin> Project release []:Введем
0.1If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]:Введем
ruCreating file c:\Projects\colortable_user_docs\docs\source\conf.py.
Creating file c:\Projects\colortable_user_docs\docs\source\index.rst.
Creating file c:\Projects\colortable_user_docs\docs\Makefile.
Creating file c:\Projects\colortable_user_docs\docs\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file c:\Projects\colortable_user_docs\docs\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.Запустим
.\make.bat htmlВ папке
C:\Projects\colortable_user_docs\docs\build\html\Будет создана пустая документация в формате html:
Откроем файл:
C:\Projects\colortable_user_docs\docs\build\html\index.htmlВ браузере:
Тест прошел успешно.
Это минимальная установка для Python Sphinx.
Преобразуем проект Python Sphinx к виду, пригодному для работы с CMake
Приведем проект sphinx к виду, пригодному для работы с CMake.
Удалим все созданные папки, мы будем использовать другую конфигурацию структуру папок для сборки с помощью CMake:
cd c:\Projects\colortable_user_docs\
rmdir /s/q build
rmdir /s/q docsОткроем наш проект:
cd c:\Projects\colortable_user_docs
code .Установка модулей для Python Sphinx
Для работы с CMake нам потребуется установить дополнительные модули.
Установка sphinx-cmake
Для работы с Python Sphinx в Cmake нам потребуется дополнительный модуль - sphinx-cmake. Он содержит все необходимые команды для удобной сборки проекта.
Установим модули для поддержки работы в CMake
pip install sphinx-cmakeУстановка поддержки markdown в Python Sphinx
Python Sphinx по умолчанию использует формат rst (reStructuredText ). Чтобы писать с использованием более простого и знакомого markdown мы установим дополнительный модуль, позволяющий вставлять md-файлы в проект.
Установим поддержку md в Python Sphinx:
pip install myst-parserДобавляем конфигурацию для Python Sphinx в CMake
Добавим файл конфигурации CMake:
type nul > .\cmake\sphinx.cmake.inДобавим содержимое:
# Задаем команды для сборки документации с помощью Python Sphinx
# Если Sphinx-cmake build был найден то задаем правила сборки
# https://python-cmake.github.io/sphinx-cmake/
if (Sphinx_FOUND)
sphinx_add_docs(doc
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx-build
SOURCE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/docs
OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx-doc
CONFIG_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx-doc
)
message("=== Sphinx documentation setup complete")
else()
# Если Sphinx-cmake не найден - выводим предупреждение
message(WARNING "=== Sphinx-cmake not found! I will skip documentation generation jobs!")
endif()Создадим папку:
mkdir cmake\sphinxСоздадим файлы:
type nul > cmake\sphinx\conf.py.in
type nul > cmake\sphinx\settings.cmake.inОткроем файл cmake\sphinx\conf.py.in добавим содержимое:
project = '${MY_SPHINX_PROJECT_NAME}'
copyright = '${MY_SPHINX_COPYRIGHT_NAME}'
author = '${MY_SPHINX_AUTHOR_NAME}'
release = '${MY_SPHINX_RELEASE_NAME}'
extensions = ['${MY_SPHINX_EXTENSIONS_NAME}']
templates_path = ['_templates']
exclude_patterns = []
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}
language = 'ru'
html_theme = '${MY_SPHINX_HTML_THEME}'
html_static_path = ['_static']Откроем файл cmake\sphinx\settings.cmake.in добавим содержимое:
# Задаем имя проекта
set(MY_SPHINX_PROJECT_NAME "colortable")
# Задаем Copyright
set(MY_SPHINX_COPYRIGHT_NAME "2025, Алтунин Василий")
# Задаем Автора
set(MY_SPHINX_AUTHOR_NAME "Алтунин Василий")
# Задаем Версию
set(MY_SPHINX_RELEASE_NAME "0.1")
# Задаем расширения Sphinx через пробел
set(MY_SPHINX_EXTENSIONS_NAME "myst_parser")
# Задаем расширения Sphinx через пробел
set(MY_SPHINX_HTML_THEME "alabaster")
# Создаем папку для конфигурации в папке build
make_directory(${CMAKE_CURRENT_BINARY_DIR}/sphinx-doc)
# Создаем файл с собранной по шаблону конфигурацией
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/cmake/sphinx/conf.py.in"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx-doc/conf.py"
)Чтобы не перегружать файл настроек настройками Sphinx мы задаем настройки которые касаются исключительно работы Python Sphinx в отдельном файле.
В файл cmake\settings.cmake.in добавим:
# Добавляем файл с конфигурацией Python Sphinx к настройкам
include(${PROJECT_SOURCE_DIR}/cmake/sphinx/settings.cmake.in)В файл cmake\conf.cmake.in добавим:
find_package(Sphinx)В конец файла CMakeLists.txt добавим:
# Настраиваем документацию sphinx
include(${PROJECT_SOURCE_DIR}/cmake/sphinx.cmake.in)Добавляем содержимое содержимое в документацию Python Sphinx
Мы подготовили все необходимые настройки, но самой документации у нас пока нет, давайте её добавим.
Создадим папку для документации:
cd c:\Projects\colortable_user_docs
mkdir docsСоздадим файлы для разделов:
type nul > docs\index.rst
type nul > docs\install.md
type nul > docs\usage.md Добавим содержимое для файла docs\index.rst:
.. Основной файл документации. Его содержимое будет выводится на главной странице.
.. Заголовок страницы, обязательно должен быть полностью подчеркнут символами ===
Документация colortable
=======================
Данная документация описывает применение программы colortable
.. toctree::
:maxdepth: 2
:caption: Содержимое:
install.md
usage.mdДанный файл описывает главную страницу нашей документации, а так же структуру оглавления.
Добавим содержимое для файла docs\install.md:
# Установка
Загрузите дистрибутив по [ссылке](https://blog.altuninvv.ru)
Запустите установщик `colortable-0.1-win64.msi`
Следуйте инструкция установщика.Добавим содержимое для файла usage.md:
# Запуск программы
Для запуска программы запустите файл:
`colortable.exe`
из папки с установленной программой.Запустим конфигурирование:
cmake -S . -B buildЗапустим сборку документации:
cmake --build build --target=doc[1/1] Generate documentation for doc
Running Sphinx v8.2.3
loading translations [ru]... done
WARNING: html_static_path entry '_static' is placed inside outdir
loading pickled environment... done
myst v4.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 3 source files that are out of date
updating environment: 0 added, 3 changed, 3 removed
reading sources... [100%] usage
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to C:\projects\colortable_user_docs\build\sphinx-doc\_static\basic.css
Writing evaluated template result to C:\projects\colortable_user_docs\build\sphinx-doc\_static\documentation_options.js
Writing evaluated template result to C:\projects\colortable_user_docs\build\sphinx-doc\_static\language_data.js
Writing evaluated template result to C:\projects\colortable_user_docs\build\sphinx-doc\_static\alabaster.css
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] usage
generating indices... genindex done
writing additional pages... search done
dumping search index in Russian (code: ru)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in build\sphinx-doc.Откроем файл:
C:\projects\colortable_user_docs\build\sphinx-doc\index.htmlУ нас получится:
Установка темы от Read The Docs в Python Sphinx
Создавая документацию для библиотеки с помощью doxygen мы использовали тему от Read The Docs. Она хорошо выглядит и будет неплохо унифицировать внешний вид документации для библиотеки с документацией для пользователя. Этого легко достич установив соответствующую тему.
Установим тему sphinx_rtd_theme:
pip install sphinx_rtd_themeОткроем файл
Откроем файл cmake\sphinx\settings.cmake.in
Заменим строку:
set(MY_SPHINX_HTML_THEME "alabaster")На:
set(MY_SPHINX_HTML_THEME "sphinx_rtd_theme")Запустим сборку документации
cmake --build build --target=docОткроем документацию после сборки:
Теперь наша документация выглядит намного лучше.
Добавляем вложенные разделы
Документация к программе может содержать множество разделов и подразделов. В Python Sphinx создать подраздел очень просто.
Допустим нам нужно создать раздел о программе с двумя страницами :
Описание
Автор
Создадим папку:
mkdir docs\aboutСоздадим файлы:
type nul > docs\about\index.rst
type nul > docs\about\about.md
type nul > docs\about\author.mdДобавим содержимое для файла docs\about\index.rst:
О программе
===========
.. toctree::
:maxdepth: 1
about.md
author.mdДобавим содержимое для файла docs\about\about.md:
# Описание
Программа выводит таблицу цветов поддерживаемых консолью.Добавим содержимое для файла docs\about\author.md:
# Автор
Автор - __Алтунин Василий__
Сайт - [https://blog.altuninvv.ru](https://blog.altuninvv.ru)Изменим содержимое файла docs\index.rst:
.. Основной файл документации. Его содержимое будет выводится на главной странице.
.. Заголовок страницы, обязательно должен быть полностью подчеркнут символами ===
Документация colortable
=======================
Данная документация описывает применение программы colortable
.. toctree::
:maxdepth: 2
:caption: Содержимое:
install.md
usage.md
about/index.rstЗапустим сборку документации
cmake --build build --target=docУ нас появился вложенный раздел:
Со своей главной страницей и разделами:
Добавление изображений в документацию
Возможно вы захотите добавить скриншоты или схемы к вашей документации.
Создадим папку для изображений:
mkdir docs\_static Для примера используем изображение:
Сохраните изображение из браузера в папку:
C:\Projects\colortable_user_docs\docs\_static\ Назовем его:
screen_app.pngЗаменим содержимое файла usage.md:
# Запуск программы
Для запуска программы запустите файл:
`colortable.exe`
из папки с установленной программой.
После запуска на экран будет выведена таблица:
Запустим сборку документации
cmake --build build --target=docИзображение будет добавлено в документацию:
Заключение
Сегодня мы создали документацию для самой программы с использованием Pyrhon Sphinx и CMake:
Установили Pyhton Sphinx;
Создали тестовый проект Pyhton Sphinx и собрали его;
Установили модуль для CMake sphinx-cmake и модуль поддержки markdown - myst-parser;
Добавили конфигурацию для Pyhton Sphinx в CMake;
Добавили содержимое для документации;
Установили тему от Read The Docs;
Рассмотрели добавление вложенных разделов.
Добавить комментарий