From bd8b054ff5009f36450dc65896f09edaa8949454 Mon Sep 17 00:00:00 2001 From: Ewoud Kohl van Wijngaarden Date: Sat, 17 Jan 2026 17:30:50 +0100 Subject: [PATCH 1/6] Use PANDOC_EXECUTABLE variable set by find_program --- CMakeLists.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 98213013..b33bea1a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -655,7 +655,7 @@ set(PANDOC_OPTS --toc --toc-depth=2 add_custom_command( OUTPUT ${OUTPUT_HTML_DE} - COMMAND pandoc ${PANDOC_OPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/de/metadata.yaml --output=${OUTPUT_HTML_DE} ${DOC_DE} DEPENDS ${DOC_DE} @@ -666,7 +666,7 @@ add_custom_command( add_custom_command( OUTPUT ${OUTPUT_HTML_EN} - COMMAND pandoc ${PANDOC_OPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/en/metadata.yaml --output=${OUTPUT_HTML_EN} ${DOC_EN} DEPENDS ${DOC_EN} @@ -677,7 +677,7 @@ add_custom_command( add_custom_command( OUTPUT ${OUTPUT_HTML_ES} - COMMAND pandoc ${PANDOC_OPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/es/metadata.yaml --output=${OUTPUT_HTML_ES} ${DOC_ES} DEPENDS ${DOC_ES} @@ -753,7 +753,7 @@ set(PANDOC_CHUNKEDOPTS --toc --toc-depth=2 --split-level=1) add_custom_command( OUTPUT ${OUTPUT_CHUNKEDHTML_DE}/index.html - COMMAND pandoc ${PANDOC_CHUNKEDOPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_CHUNKEDOPTS} --resource-path=".:Documentation:Documentation/de:doc:doc/de" --metadata-file=Documentation/de/metadata.yaml --output=${OUTPUT_CHUNKEDHTML_DE} ${DOC_DE} @@ -765,7 +765,7 @@ add_custom_command( add_custom_command( OUTPUT ${OUTPUT_CHUNKEDHTML_EN}/index.html - COMMAND pandoc ${PANDOC_CHUNKEDOPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_CHUNKEDOPTS} --resource-path=".:Documentation:Documentation/en:doc:doc/en" --metadata-file=Documentation/en/metadata.yaml --output=${OUTPUT_CHUNKEDHTML_EN} ${DOC_EN} @@ -777,7 +777,7 @@ add_custom_command( add_custom_command( OUTPUT ${OUTPUT_CHUNKEDHTML_ES}/index.html - COMMAND pandoc ${PANDOC_CHUNKEDOPTS} + COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_CHUNKEDOPTS} --resource-path="doc/en:Documentation/en:.:Documentation:Documentation/es:doc:doc/es" --metadata-file=Documentation/es/metadata.yaml --output=${OUTPUT_CHUNKEDHTML_ES} ${DOC_ES} From 9380bc39d64528935e987d59e9298882ed1a42ed Mon Sep 17 00:00:00 2001 From: Bruno Kleinert Date: Mon, 16 Feb 2026 07:40:08 +0100 Subject: [PATCH 2/6] Add variables for monolithic documentation file locations This makes it clearer how items are related. This is an edit of Edwoud's work, but leaves the "chunked HTML" as is. pandoc is not that straight-forward to handle when it works in 'chunked HTML mode'. --- CMakeLists.txt | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index b33bea1a..78b046ad 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -435,6 +435,7 @@ set(DOC_DE Documentation/de/config-counter.md Documentation/de/automatic.md ) + set(DOCDATA_DE ${PROJECT_SOURCE_DIR}/Documentation/de/config_layers_de.png ${PROJECT_SOURCE_DIR}/Documentation/de/control_list_de.png @@ -640,13 +641,17 @@ set(DOCDATA ${PROJECT_SOURCE_DIR}/Documentation/style.css ) -set(OUTPUT_HTML_DE ${CMAKE_BINARY_DIR}/doc/de/index.html) -set(OUTPUT_HTML_EN ${CMAKE_BINARY_DIR}/doc/en/index.html) -set(OUTPUT_HTML_ES ${CMAKE_BINARY_DIR}/doc/es/index.html) +set(OUTPUT_HTML ${CMAKE_BINARY_DIR}/doc) +set(OUTPUT_HTML_DE ${OUTPUT_HTML}/de) +set(OUTPUT_HTML_DE_INDEX ${OUTPUT_HTML_DE}/index.html) +set(OUTPUT_HTML_EN ${OUTPUT_HTML}/en) +set(OUTPUT_HTML_EN_INDEX ${OUTPUT_HTML_EN}/index.html) +set(OUTPUT_HTML_ES ${OUTPUT_HTML}/es) +set(OUTPUT_HTML_ES_INDEX ${OUTPUT_HTML_ES}/index.html) -file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/doc/de) -file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/doc/en) -file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/doc/es) +file(MAKE_DIRECTORY ${OUTPUT_HTML_DE}) +file(MAKE_DIRECTORY ${OUTPUT_HTML_EN}) +file(MAKE_DIRECTORY ${OUTPUT_HTML_ES}) set(PANDOC_OPTS --toc --toc-depth=2 --standalone @@ -654,47 +659,47 @@ set(PANDOC_OPTS --toc --toc-depth=2 --template=Documentation/template.html) add_custom_command( - OUTPUT ${OUTPUT_HTML_DE} + OUTPUT ${OUTPUT_HTML_DE_INDEX} COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/de/metadata.yaml - --output=${OUTPUT_HTML_DE} ${DOC_DE} - DEPENDS ${DOC_DE} + --output=${OUTPUT_HTML_DE_INDEX} ${DOC_DE} + DEPENDS ${DOC_DE} ${OUTPUT_HTML_DE} WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Generating German HTML documentation" VERBATIM ) add_custom_command( - OUTPUT ${OUTPUT_HTML_EN} + OUTPUT ${OUTPUT_HTML_EN_INDEX} COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/en/metadata.yaml - --output=${OUTPUT_HTML_EN} ${DOC_EN} - DEPENDS ${DOC_EN} + --output=${OUTPUT_HTML_EN_INDEX} ${DOC_EN} + DEPENDS ${DOC_EN} ${OUTPUT_HTML_EN} WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Generating English HTML documentation" VERBATIM ) add_custom_command( - OUTPUT ${OUTPUT_HTML_ES} + OUTPUT ${OUTPUT_HTML_ES_INDEX} COMMAND ${PANDOC_EXECUTABLE} ${PANDOC_OPTS} --metadata-file=Documentation/es/metadata.yaml - --output=${OUTPUT_HTML_ES} ${DOC_ES} - DEPENDS ${DOC_ES} + --output=${OUTPUT_HTML_ES_INDEX} ${DOC_ES} + DEPENDS ${DOC_ES} ${OUTPUT_HTML_ES} WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} COMMENT "Generating Spanish HTML documentation" VERBATIM ) add_custom_target(doc - DEPENDS ${OUTPUT_HTML_DE} ${OUTPUT_HTML_EN} ${OUTPUT_HTML_ES} + DEPENDS ${OUTPUT_HTML_DE_INDEX} ${OUTPUT_HTML_EN_INDEX} ${OUTPUT_HTML_ES_INDEX} ) foreach(DOCDATA ${DOCDATA}) add_custom_command(TARGET doc POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${DOCDATA} - ${PROJECT_BINARY_DIR}/doc + ${OUTPUT_HTML} ) endforeach() @@ -702,7 +707,7 @@ foreach(DOCDATA_DE ${DOCDATA_DE}) add_custom_command(TARGET doc POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${DOCDATA_DE} - ${PROJECT_BINARY_DIR}/doc/de + ${OUTPUT_HTML_DE} ) endforeach() @@ -710,7 +715,7 @@ foreach(DOCDATA_EN ${DOCDATA_EN}) add_custom_command(TARGET doc POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${DOCDATA_EN} - ${PROJECT_BINARY_DIR}/doc/en + ${OUTPUT_HTML_EN} ) endforeach() @@ -718,7 +723,7 @@ foreach(DOCDATA_ES ${DOCDATA_ES}) add_custom_command(TARGET doc POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy ${DOCDATA_ES} - ${PROJECT_BINARY_DIR}/doc/es + ${OUTPUT_HTML_ES} ) endforeach() From fb77f8bed6b6445475d3c1190e90f9c0db219dd7 Mon Sep 17 00:00:00 2001 From: Ewoud Kohl van Wijngaarden Date: Fri, 6 Feb 2026 17:59:43 +0100 Subject: [PATCH 3/6] Install doc files using file() Instead of using a custom command, this uses the built in functionality. --- CMakeLists.txt | 35 ++++------------------------------- 1 file changed, 4 insertions(+), 31 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 78b046ad..a6fa2338 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -695,37 +695,10 @@ add_custom_target(doc DEPENDS ${OUTPUT_HTML_DE_INDEX} ${OUTPUT_HTML_EN_INDEX} ${OUTPUT_HTML_ES_INDEX} ) -foreach(DOCDATA ${DOCDATA}) - add_custom_command(TARGET doc POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy - ${DOCDATA} - ${OUTPUT_HTML} - ) -endforeach() - -foreach(DOCDATA_DE ${DOCDATA_DE}) - add_custom_command(TARGET doc POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy - ${DOCDATA_DE} - ${OUTPUT_HTML_DE} - ) -endforeach() - -foreach(DOCDATA_EN ${DOCDATA_EN}) - add_custom_command(TARGET doc POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy - ${DOCDATA_EN} - ${OUTPUT_HTML_EN} - ) -endforeach() - -foreach(DOCDATA_ES ${DOCDATA_ES}) - add_custom_command(TARGET doc POST_BUILD - COMMAND ${CMAKE_COMMAND} -E copy - ${DOCDATA_ES} - ${OUTPUT_HTML_ES} - ) -endforeach() +file(COPY ${DOCDATA} DESTINATION ${OUTPUT_HTML}) +file(COPY ${DOCDATA_DE} DESTINATION ${OUTPUT_HTML_DE}) +file(COPY ${DOCDATA_EN} DESTINATION ${OUTPUT_HTML_EN}) +file(COPY ${DOCDATA_ES} DESTINATION ${OUTPUT_HTML_ES}) add_custom_target(doc-for-web DEPENDS doc From d75eb2bd760090fbe991dff0f28a951fc1b973ce Mon Sep 17 00:00:00 2001 From: Ewoud Kohl van Wijngaarden Date: Fri, 6 Feb 2026 18:32:32 +0100 Subject: [PATCH 4/6] Build documentation if pandoc is found --- CMakeLists.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index a6fa2338..d979eebc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -691,9 +691,11 @@ add_custom_command( VERBATIM ) -add_custom_target(doc - DEPENDS ${OUTPUT_HTML_DE_INDEX} ${OUTPUT_HTML_EN_INDEX} ${OUTPUT_HTML_ES_INDEX} -) +if(PANDOC_EXECUTABLE) + add_custom_target(doc ALL + DEPENDS ${OUTPUT_HTML_DE_INDEX} ${OUTPUT_HTML_EN_INDEX} ${OUTPUT_HTML_ES_INDEX} + ) +endif() file(COPY ${DOCDATA} DESTINATION ${OUTPUT_HTML}) file(COPY ${DOCDATA_DE} DESTINATION ${OUTPUT_HTML_DE}) From 0ad07c331029cefb50a0497026f3ab32a94a732b Mon Sep 17 00:00:00 2001 From: Ewoud Kohl van Wijngaarden Date: Fri, 6 Feb 2026 18:32:50 +0100 Subject: [PATCH 5/6] Install documentation to destination dir --- CMakeLists.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index d979eebc..4b4fde0e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -389,6 +389,7 @@ target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_SOURCE_DIR}) configure_file(Version.cpp.in Version.cpp @ONLY) set(CMAKE_INSTALL_BINDIR ".") +set(CMAKE_INSTALL_DOCDIR "doc") set(DATADIR ".") install(TARGETS ${PROJECT_NAME}) @@ -692,6 +693,7 @@ add_custom_command( ) if(PANDOC_EXECUTABLE) + install(DIRECTORY ${OUTPUT_HTML}/ DESTINATION ${CMAKE_INSTALL_DOCDIR}) add_custom_target(doc ALL DEPENDS ${OUTPUT_HTML_DE_INDEX} ${OUTPUT_HTML_EN_INDEX} ${OUTPUT_HTML_ES_INDEX} ) From d86c52e5ba93b5ef2f7bb215b0fa1cedcbf50e31 Mon Sep 17 00:00:00 2001 From: Bruno Kleinert Date: Mon, 16 Feb 2026 08:25:12 +0100 Subject: [PATCH 6/6] Delete chunked HTML directories in clean target --- CMakeLists.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4b4fde0e..b364938d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -773,6 +773,20 @@ add_custom_target(chunked-doc DEPENDS ${OUTPUT_CHUNKEDHTML_DE}/index.html ${OUTPUT_CHUNKEDHTML_EN}/index.html ${OUTPUT_CHUNKEDHTML_ES}/index.html ) +# Required for pandoc --write=chunkedhtml +# +# In that mode, pandoc is not idempotent and the target directories we want it +# to write to, need to be gone before it is called one more time. +# I.e., if you're working on the chunked HTML output, ideally call +# cmake [...] --clean-first --target chunked-doc +set_property( + TARGET chunked-doc + APPEND + PROPERTY ADDITIONAL_CLEAN_FILES + ${CMAKE_BINARY_DIR}/chunkedhtml/de + ${CMAKE_BINARY_DIR}/chunkedhtml/en + ${CMAKE_BINARY_DIR}/chunkedhtml/es) + foreach(DOCDATA ${DOCDATA}) add_custom_command(TARGET chunked-doc POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy