Add CMake module and basic config to generate documentation with Sphinx

Author: Martchus

CMakeLists.txt

@@ -84,6 +84,7 @@ set(CMAKE_MODULE_FILES
     cmake/modules/WindowsResources.cmake
     cmake/modules/TemplateFinder.cmake
     cmake/modules/Doxygen.cmake
+    cmake/modules/Sphinx.cmake
     cmake/modules/ListToString.cmake
     cmake/modules/ShellCompletion.cmake
     cmake/modules/DevelUtilities.cmake
@@ -96,6 +97,7 @@ set(CMAKE_TEMPLATE_FILES
     cmake/templates/desktop.in
     cmake/templates/appdata.xml.in
     cmake/templates/doxygen.in
+    cmake/templates/sphinx-conf.py.in
     cmake/templates/global.h.in
     cmake/templates/version.h.in
     cmake/templates/template.pc.in)

README.md

@@ -64,6 +64,8 @@ These build instructions apply to `c++utilities` but also to my other projects u
 * CMake (at least 3.17.0) and Ninja or GNU Make
 * cppunit for unit tests (optional)
 * Doxygen for API documentation (optional)
+* Sphinx with MyST-Parser for general documentation (optional, under Arch Linux install
+  `python-myst-parser`)
 * Graphviz for diagrams in the API documentation (optional)
 * clang-format and cmake-format for tidying (optional)
 * llvm-profdata, llvm-cov and cppunit for source-based code coverage analysis (optional)

cmake/modules/Sphinx.cmake

@@ -0,0 +1,52 @@
+cmake_minimum_required(VERSION 3.17.0 FATAL_ERROR)
+
+if (NOT BASIC_PROJECT_CONFIG_DONE)
+    message(FATAL_ERROR "Before including the Sphinx module, the BasicConfig module must be included.")
+endif ()
+
+option(NO_SPHINX "whether creation of Sphinx targets is disabled (enabled by default)" OFF)
+if (NO_SPHINX)
+    return()
+endif ()
+
+# find doxygen.h template
+include(TemplateFinder)
+find_template_file("sphinx-conf.py" CPP_UTILITIES SPHINX_TEMPLATE_FILE)
+
+# find executables
+find_program(SPHINX_BIN sphinx-build)
+if (NOT SPHINX_BIN)
+    message(WARNING "Sphinx not found, unable to add target for generating documentation for ${META_TARGET_NAME}")
+    return()
+endif ()
+
+# configure paths and "conf.py"
+set(SPHINX_INPUT_FILES ${SPHINX_DOC_FILES})
+if (NOT SPHINX_SOURCE_DIR)
+    set(SPHINX_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+endif ()
+set(SPHINX_CONFIG_DIR "${CMAKE_CURRENT_BINARY_DIR}/sphinxconfig")
+set(SPHINX_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc")
+configure_file("${SPHINX_TEMPLATE_FILE}" "${SPHINX_CONFIG_DIR}/conf.py")
+
+# add target for generating documentation
+add_custom_target("${META_TARGET_NAME}_sphinxdoc" COMMAND "${SPHINX_BIN}" -c "${SPHINX_CONFIG_DIR}" "${SPHINX_SOURCE_DIR}" "${SPHINX_OUTPUT_DIR}")
+if (NOT TARGET sphinxdoc)
+    add_custom_target(sphinxdoc)
+endif ()
+add_dependencies(sphinxdoc "${META_TARGET_NAME}_sphinxdoc")
+
+# add install target for API documentation
+if (NOT META_NO_INSTALL_TARGETS AND ENABLE_INSTALL_TARGETS)
+    install(
+        DIRECTORY "${SPHINX_OUTPUT_DIR}"
+        DESTINATION "${META_DATA_DIR}"
+        COMPONENT doc
+        OPTIONAL)
+    if (NOT TARGET install-doc)
+        add_custom_target(install-doc COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=doc -P
+                                              "${CMAKE_BINARY_DIR}/cmake_install.cmake")
+    endif ()
+endif ()
+
+message(STATUS "Added target for building documentation for ${META_TARGET_NAME} with Sphinx")

cmake/templates/sphinx-conf.py.in

@@ -0,0 +1,32 @@
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+project = '@META_APP_NAME@'
+copyright = '@META_APP_COPYRIGHT@'
+author = '@META_APP_AUTHOR@'
+version = '@META_VERSION_MAJOR@.@META_VERSION_MINOR@.@META_VERSION_PATCH@'
+release = '@META_RELEASE_DATE@'
+
+# -- General configuration ------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+exclude_patterns = [
+    '.github', # exclude GitHub issue templates
+    'syncthing/go/**', # exclude files from Syncthing itself
+    'CMakeLists*', # avoid CMakeLists.txt from being considered normal txt files
+    '**/CMakeLists*', # avoid CMakeLists.txt from being considered normal txt files
+    'LICENSES-*', # exclude license compilations
+]
+extensions = [
+    'myst_parser', # enable Markdown support
+]
+language = 'en'
+master_doc = 'index'
+pygments_style = 'sphinx'
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+templates_path = ['_templates']
+
+# -- Options for HTML output ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = 'alabaster'