Christopher M. Punches
3b7091dc4b
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.
99 lines
3.9 KiB
CMake
99 lines
3.9 KiB
CMake
# ---------------------------------------------------------------------
|
|
# 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()
|
