При создании документации пользователя важным фактором является не просто её наличие, но и формат. Наиболее удобным для всех пользователей является формат pdf. Он позволяет открывать документацию не только на ПК, но на любом мобильном устройстве!

В прошлой статье мы рассмотрели создание документации пользователя с помощью Python Sphinx. Сегодня мы рассмотрим создание этой же документации в формате pdf, с помощью TexLive, Python Sphinx и Cmake.

Установка TexLive

Для создания pdf-файла нам потребуется инструментарий для работы с latex. Единственный рабочий в Windows 10 - установить его отдельно с помощью официального установщика! 

Обратите внимание! У вас может быть установлена и доступна только одна версия LatexLive. Версия для MSYS2 не работает как положено с кириллическими шрифтами и имеет ряд других проблем. К тому же версия в MSYS2 это устаревшая версия, в то время как официальный установщик предоставляет версию 2025!

Если у вас уже были установлены какие либо утилиты или пакеты связанные с latex, вам нужно будет их удалить. В противном случае возможно непредсказуемое поведение при сборки pdf!

Для установки вам потребуется как минимум 3.5 Гб свободного места на диске!

mkdir c:\texinst
cd c:\texinst
wget  https://mirror.ctan.org/systems/texlive/tlnet/install-tl.zip
pacman -S unzip
unzip install-tl.zip

Определим имя папки

dir

В моем случае это

install-tl-20250930

При выпуске новой версии имя папки изменится!

Создадим файл с профилем:

cd install-tl-20250930
type nul > sphinx-support.profile

Добавим к файлу содержимое:

# texlive.profile written on Tue Sep 30 06:51:12 2025 UTC
# It will NOT be updated and reflects only the
# installation profile at installation time.
selected_scheme scheme-custom
TEXDIR c:/texlive
TEXMFCONFIG ~/.texlive2025/texmf-config
TEXMFHOME ~/texmf
TEXMFLOCAL c:/texlive/texmf-local
TEXMFSYSCONFIG c:/texlive/texmf-config
TEXMFSYSVAR c:/texlive/texmf-var
TEXMFVAR ~/.texlive2025/texmf-var
binary_windows 1
collection-basic 1
collection-bibtexextra 1
collection-binextra 1
collection-context 1
collection-fontsextra 1
collection-fontsrecommended 1
collection-fontutils 1
collection-formatsextra 1
collection-langcyrillic 1
collection-langenglish 1
collection-latex 1
collection-latexextra 1
collection-latexrecommended 1
collection-luatex 1
collection-mathscience 1
collection-metapost 1
collection-pictures 1
collection-plaingeneric 1
collection-wintools 1
collection-xetex 1
instopt_adjustpath 1
instopt_adjustrepo 1
instopt_letter 0
instopt_portable 0
instopt_write18_restricted 1
tlpdbopt_autobackup 1
tlpdbopt_backupdir tlpkg/backups
tlpdbopt_create_formats 1
tlpdbopt_desktop_integration 1
tlpdbopt_file_assocs 1
tlpdbopt_generate_updmap 0
tlpdbopt_install_docfiles 0
tlpdbopt_install_srcfiles 0
tlpdbopt_post_code 1
tlpdbopt_sys_bin /usr/local/bin
tlpdbopt_sys_info /usr/local/share/info
tlpdbopt_sys_man /usr/local/share/man
tlpdbopt_w32_multi_user 0

Запустим:

install-tl-windows -no-interaction -no-doc-install -no-src-install --no-gui -texdir c:\texlive  -profile sphinx-support.profile

Для установки потребуется длительное время. Здесь всё зависит от вашего интернет соединения. Вместе с тем, нужно установить 3775 пакетов, поэтому в среднем установка занимает около полтора часа. У меня на виртуальной машине она завершилась за 1:18:32. Еще около пяти минут займет распаковка и настройка.

Установщик автоматически добавить путь в переменную Path для текущего пользователя:

PATH=C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Windows\System32\OpenSSH\;C:\Users\user\AppData\Local\Microsoft\WindowsApps;C:\msys64\mingw64\bin;C:\msys64\usr\bin;C:\Users\user\AppData\Local\Microsoft\WindowsApps;c:\texlive\bin\windows

Обязательно закройте все окна консоли cmd, после внесения изменений в переменную path!

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

Начнем мы с проекта, размещенного в git-репозитории.

У вас уже должен быть установлен Pyhton Sphinx и все нужные модули, согласно статьи.

Если папка:

c:\projects\colortable_user_docs_pdf

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

cd c:\projects
rmdir /q/s colortable_user_docs_pdf

Мы будем использовать проект из 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_pdf\ .\colortable_user_docs_pdf\

Добавляем конфигурацию CMake для создания pdf-версии документации

Откроем проект:

cd c:\projects\colortable_user_docs_pdf
code .

Python Sphinx у нас уже используется для создания HTML-версии документации. Для создания latex-версии нам понадобится еще один такой же блок настроек, c небольшими отличиями.

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

type nul > cmake\sphinx\sphinx_target.cmake.in

Добавим для него содержимое:

# Шаблон для сборки Sphinx


# Создаем папку для конфигурации в папке build
make_directory(${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR})

# Создаем файл с собранной по шаблону конфигурацией
configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/sphinx/conf.py.in"
    "${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}/conf.py"
)

# Если Sphinx-cmake build был найден то задаем правила сборки
# https://python-cmake.github.io/sphinx-cmake/
if (Sphinx_FOUND)
        sphinx_add_docs(${MY_SPHINX_TARGET}
            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx-build
            SOURCE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/docs
            OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}
            CONFIG_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}
            BUILDER ${MY_SPHINX_BUILDER}
        )
    message("=== Sphinx documentation for ${MY_SPHINX_TARGET} setup complete")
else()
    # Если Sphinx-cmake не найден - выводим предупреждение
    message(WARNING "=== Sphinx-cmake not found! I will skip documentation generation jobs!")
endif()

Откроем файл cmake\sphinx\settings.cmake.in

И удалим из него строки:

# Создаем папку для конфигурации в папке 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"
)

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

# Задаем команды для сборки документации с помощью Python Sphinx

# Задаем настройки для шаблона
set(MY_SPHINX_BUILDER html)
set(MY_SPHINX_TARGET doc)
set(MY_SPHINX_BIN_DIR sphinx-doc)

# Используем шаблон для генерации target
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/sphinx/sphinx_target.cmake.in)

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

type nul > cmake\latex.cmake.in

Добавим содержимое:

find_program(XELATEX_COMPILER XELATEX)
if(NOT XELATEX_COMPILER)

    message(WARNING "=== Pdflatex not found! I will skip pdf generation for user docs!")

else()

# Задаем настройки для шаблона
set(MY_SPHINX_BUILDER latex)
set(MY_SPHINX_TARGET latex)
set(MY_SPHINX_BIN_DIR sphinx-doc-pdf)

# Используем шаблон для генерации target
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/sphinx/sphinx_target.cmake.in)

# Команда запускает сборку Pdf с помощью файла make.bat
add_custom_command(
    OUTPUT  ${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}/${PROJECT_NAME}.pdf
    COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}/make.bat   
    DEPENDS latex
    COMMENT "Compiling main.tex to PDF"
)

# Добавляем target зависящий от latex
add_custom_target(pdf
    DEPENDS latex ${CMAKE_CURRENT_BINARY_DIR}/${MY_SPHINX_BIN_DIR}/${PROJECT_NAME}.pdf
)

message("=== LATEX PDF generator setup complete")   

endif()

Откроем файл 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}'

latex_elements = {
    'extraclassoptions': 'openany,oneside',
}

latex_engine = 'xelatex'

Откроем CMakeLists.txt добавим в конец файла:

# Настраиваем генерацию pdf
include(${PROJECT_SOURCE_DIR}/cmake/latex.cmake.in)

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

cmake -S . -B build

-- Building for: Ninja
-- The CXX compiler identification is GNU 15.2.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/msys64/mingw64/bin/c++.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
...
BUILD_SHARED_LIBS=ON
=== Library build set to SHARED
=== Settings setup complete
    Library will be build as SHARED
=== Building EXTERNAL docs
=== Doxygen config generated
=== Libconf settings complete
-- Could NOT find Doxygen (missing: DOXYGEN_EXECUTABLE)
=== Targets settings complete
=== Install settings complete
-- Found Sphinx: C:/msys64/mingw64/bin/sphinx-build.exe (found version "8.2.3")
== Shared dependency setup
=== Sphinx documentation for doc setup complete
=== Sphinx documentation for latex setup complete
=== LATEX PDF generator setup complete
-- Configuring done (6.6s)
-- Generating done (0.0s)
-- Build files have been written to: C:/projects/colortable_user_docs_pdf/build

Строки:

=== Sphinx documentation for doc setup complete
=== Sphinx documentation for latex setup complete
=== LATEX PDF generator setup complete

Указывают, что конфигурация для Sphinx и Latex прошла успешно.

Запустим сборку HTML-версии

cmake --build build --target=doc

Будет создана папка:

C:\projects\colortable_user_docs_pdf\build\sphinx-doc

Запустим 

cmake --build build --target=pdf

[1/2] Generate documentation for latex
Running Sphinx v8.2.3
loading translations [ru]... done
...
Writing evaluated template result to C:\projects\colortable_user_docs_pdf\build\sphinx-doc-pdf\sphinxmessages.sty
build succeeded.
The LaTeX files are in build\sphinx-doc-pdf.
[2/2] Compiling main.tex to PDF
Latexmk: Invoked as 'c:\texlive\texmf-dist\scripts\latexmk\latexmk'
Rc files read:
 latexmkrc
Latexmk: This is Latexmk, John Collins, 15 June 2025. Version 4.87.
No existing .aux file, so I'll make a simple one, and require run of *latex.
Latexmk: applying rule 'pdflatex'...
Rule 'pdflatex':  Reasons for rerun
Category 'other':
 Rerun of 'pdflatex' forced or previously required:
   Reason or flag: 'Initial setup'
...
Output written on colortable.pdf (6 pages).
Transcript written on colortable.log.
Latexmk: Getting log file 'colortable.log'
Latexmk: Examining 'colortable.fls'
Latexmk: Examining 'colortable.log'
Latexmk: Log file says output to 'colortable.pdf'
Latexmk: Index file 'colortable.idx' was written
Latexmk: Using bibtex to make bibliography file(s).
Latexmk: All targets (colortable.pdf) are up-to-date

В папке:

C:\projects\colortable_user_docs_pdf\build\sphinx-doc-pdf

Будет создан файл:

colortable.pdf

Скриншоты страниц:

Заключение

Сегодня мы рассмотрели создание документации в формате pdf, с помощью TexLive, Python Sphinx и Cmake:

Установили инструментарий для работы с latex с помощью установщика TexLive;

Внесли изменения в конфигурацию CMake для одновременной сборки html и pdf версий документации;

Проверили сборку документации в формате pdf.