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

108
CMakeLists.txt
View File

@@ -100,100 +100,22 @@ file(WRITE ${CMAKE_BINARY_DIR}/DartConfiguration.tcl
add_subdirectory(tests)
# ---------------------------------------------------------------------
# Code reference (Doxygen) — optional 'docs' target
# Documentation
#
# The Doxygen configuration and the 'docs' target are defined in
# docs/CMakeLists.txt. The paths it builds into are named here, above
# that directory, so each is written once and the clean rule below
# refers to the same values.
#
# The subdirectory is given its own binary directory so that CMake's
# scaffolding stays out of the documentation output.
# ---------------------------------------------------------------------
option(DPM_DOCS_HTML "Generate the code reference in HTML" ON)
option(DPM_DOCS_PDF "Generate the code reference as PDF (requires LaTeX)" ON)
set(DPM_DOCS_DIR ${CMAKE_BINARY_DIR}/docs)
set(DPM_DOCS_TMP_DIR ${DPM_DOCS_DIR}/tmp)
set(DPM_DOCS_PDF_DIR ${DPM_DOCS_DIR}/pdf)
set(DPM_DOCS_HTML_DIR ${DPM_DOCS_DIR}/html)
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 ${CMAKE_BINARY_DIR}/docs/tmp)
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}/docs/OVERVIEW.md
${CMAKE_CURRENT_SOURCE_DIR}/docs/DESIGN.md
${CMAKE_CURRENT_SOURCE_DIR}/docs/CONSUMERS.md
${CMAKE_CURRENT_SOURCE_DIR}/docs/MODULES.md
${CMAKE_CURRENT_SOURCE_DIR}/docs/BUILD.md
${CMAKE_CURRENT_SOURCE_DIR}/docs/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_CURRENT_SOURCE_DIR}/include
${CMAKE_CURRENT_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 ${CMAKE_BINARY_DIR}/docs/tmp/latex
COMMAND ${CMAKE_COMMAND} -E rm -rf
${CMAKE_BINARY_DIR}/docs/pdf
COMMAND ${CMAKE_COMMAND} -E copy
${CMAKE_BINARY_DIR}/docs/tmp/latex/refman.pdf
${CMAKE_BINARY_DIR}/docs/pdf/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
${CMAKE_BINARY_DIR}/docs/html
COMMAND ${CMAKE_COMMAND} -E copy_directory
${CMAKE_BINARY_DIR}/docs/tmp/html
${CMAKE_BINARY_DIR}/docs/html
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 ${CMAKE_BINARY_DIR}/docs/tmp
COMMENT "Clearing the generators' scratch directory"
)
endif()
add_subdirectory(docs ${CMAKE_BINARY_DIR}/docs-build)
# ---------------------------------------------------------------------
# Clean
@@ -214,7 +136,7 @@ set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_CLEAN_FILES
${CMAKE_BINARY_DIR}/lib
${CMAKE_BINARY_DIR}/modules
${DPM_TEST_DIR}
${CMAKE_BINARY_DIR}/docs
${DPM_DOCS_DIR}
)
# ---------------------------------------------------------------------