Dark-Horse-Linux/dpm-core-ng
3
0
Fork 0
Code Issues Pull Requests Actions Activity

Define the documentation build in docs/CMakeLists.txt and collect the prose

Browse Source 
The Doxygen configuration, the page list, and the docs target live in
docs/, and the written documents live in docs/PROSE/, leaving the
top-level file with the output paths and the add_subdirectory call.

The subdirectory is given its own binary directory so that CMake's
scaffolding stays out of the documentation output, which holds pdf/ and
html/ and nothing else.

Paths both files need are set once above the call: the child's output
and cleanup and the parent's clean rule refer to the same variables.
This commit is contained in:
Chris Punches
2026-08-16 00:37:33 -04:00
parent 64839e3933
commit 3b7091dc4b
10 changed files with 118 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/CMakeLists.txt Normal file
View File

@@ -0,0 +1,98 @@
# ---------------------------------------------------------------------
# Code reference (Doxygen) — optional 'docs' target
#
# The output paths come from the top-level file, which defines them
# before adding this directory so that each is written in one place.
# ---------------------------------------------------------------------
option(DPM_DOCS_HTML "Generate the code reference in HTML" ON)
option(DPM_DOCS_PDF "Generate the code reference as PDF (requires LaTeX)" ON)
find_package(Doxygen)
if(DOXYGEN_FOUND)
# Doxygen and LaTeX both work in scratch space under docs/tmp. The
# finished document is copied up into docs/, so the directory a user
# opens holds documentation and nothing else.
set(DOXYGEN_OUTPUT_DIRECTORY ${DPM_DOCS_TMP_DIR})
set(DOXYGEN_EXTRACT_ALL YES)
set(DOXYGEN_EXTRACT_STATIC YES)
set(DOXYGEN_QUIET YES)
set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
if(DPM_DOCS_HTML)
set(DOXYGEN_GENERATE_HTML YES)
else()
set(DOXYGEN_GENERATE_HTML NO)
endif()
if(DPM_DOCS_PDF)
set(DOXYGEN_GENERATE_LATEX YES)
set(DOXYGEN_USE_PDFLATEX YES)
set(DOXYGEN_PDF_HYPERLINKS YES)
else()
set(DOXYGEN_GENERATE_LATEX NO)
endif()
# The prose documents, each rendered as its own page in the generated
# reference. Named one per line so the set of documents reaching the
# output is stated here instead of implied by a directory.
set(DPM_DOC_PAGES
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/OVERVIEW.md
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DESIGN.md
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/CONSUMERS.md
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/MODULES.md
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/BUILD.md
${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DOCUMENTATION.md
)
# Two kinds of input: include/ and src/ supply the API and internals
# reference extracted from the source, DPM_DOC_PAGES supplies the
# prose pages.
#
# One target, so `cmake --build <dir> --target docs` is the whole
# procedure and the IDE lists a single entry for it. The commands
# below run after Doxygen and place the finished documents.
doxygen_add_docs(docs
${CMAKE_SOURCE_DIR}/include
${CMAKE_SOURCE_DIR}/src
${DPM_DOC_PAGES}
COMMENT "Generating the reference with Doxygen"
)
if(DPM_DOCS_PDF)
find_program(PDFLATEX_EXECUTABLE pdflatex)
if(PDFLATEX_EXECUTABLE)
add_custom_command(TARGET docs POST_BUILD
COMMAND make -C ${DPM_DOCS_TMP_DIR}/latex
COMMAND ${CMAKE_COMMAND} -E rm -rf
${DPM_DOCS_PDF_DIR}
COMMAND ${CMAKE_COMMAND} -E copy
${DPM_DOCS_TMP_DIR}/latex/refman.pdf
${DPM_DOCS_PDF_DIR}/dpm-core-${PROJECT_VERSION}.pdf
COMMENT "Compiling the PDF reference"
)
else()
message(WARNING "DPM_DOCS_PDF is ON but pdflatex was not found; no PDF will be produced")
endif()
endif()
if(DPM_DOCS_HTML)
add_custom_command(TARGET docs POST_BUILD
COMMAND ${CMAKE_COMMAND} -E rm -rf
${DPM_DOCS_HTML_DIR}
COMMAND ${CMAKE_COMMAND} -E copy_directory
${DPM_DOCS_TMP_DIR}/html
${DPM_DOCS_HTML_DIR}
COMMENT "Placing the HTML reference"
)
endif()
# Doxygen keeps output files it judges unchanged, so a run over a
# populated scratch directory can carry pages forward from an earlier
# one. Removing it here means the next run regenerates everything,
# and leaves docs/ holding the finished documents alone.
add_custom_command(TARGET docs POST_BUILD
COMMAND ${CMAKE_COMMAND} -E rm -rf ${DPM_DOCS_TMP_DIR}
COMMENT "Clearing the generators' scratch directory"
)
endif()