Add Sphinx manpage pipeline and history command manpage
This merge request will add the baseline for building manpages using Sphinx along with the apt history manpage.
Feature
Sphinx manpages are stored in the doc/man/ directory and are added to the build target in the doc/CMakeLists.txt file like so:
if(WITH_DOC OR WITH_DOC_MANPAGES)
add_sphinx_manpages(apt-man-sphinx ALL
SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}
BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}
MANPAGES
man/apt-history apt-history "history operations for APT" 8
)
...
where MANPAGES accepts a space separated list containing the .rst file (relative to doc/), the command name, a short description, and the manpage section. Currently this does not support translations, but should provide a starting point.
The generation is based on two CMake templates:
doc/conf.py.indoc/manpages_autogen.py.in
The first is responsible for configuring Sphinx and the second reads the Sphinx manpages as given by CMake using a dataclass. CMake manually constructs this dataclass object like so:
string(APPEND MANPAGE_DEFINITIONS " ManPage(\"${rst}\", \"${name}\", \"${desc}\", [], ${section}),\n")
Notably the author field is empty. This is instead delegated to the manpage file itself as Sphinx otherwise formats the AUTHOR header in title-case.
Addition summary
-
debian/control: python3-sphinx as doc dependency during build -
CMakeLists.txt: generate Sphinxconf.py -
CMake/Documentation.cmake: function for reading and building Sphinx manpages -
doc/CMakeLists.txt: additional separate target for Sphinx manpages -
doc/man/*: manpage for theapt historycommand and index file