From 5e188475628635f3254484ed506d8abba096d469 Mon Sep 17 00:00:00 2001 From: dbiastoch Date: Wed, 3 Feb 2021 15:11:00 +0100 Subject: dlt-doc:Fix generating HTML documentation and man pages HTML documentation: -Implemented GLOB mechanism to get all md files inside '/doc' for generating html documentation -Replacing all markdown links in generated html files with the corresponding html links (using sed) -Bug fixes +Marking Doxygen as required package to get a nice error message, if it's missing +'cp' needs '-r' argument, because it includes another subdirectory with images Man Pages: -Also make use of GLOB and foreach loops to get rid of hardcoded filenames Signed-off-by: dbiastoch --- README.md | 2 +- doc/CMakeLists.txt | 179 ++++++++++++++++++++--------------------------------- 2 files changed, 67 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 45dabcf..6346bc3 100644 --- a/README.md +++ b/README.md @@ -156,7 +156,7 @@ configure DLT to exactly suit your needs, how to control the behvaiour of running instances and how to interface DLT with existing system through provided adaptors. -The man pages are generated with *pandoc*. +The man pages are generated with *pandoc*, which also needs *asciidoc* as dependency. Build manpages (initally or because something changed) with e.g. ```bash diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index f7dffb0..d0f2d67 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -25,19 +25,32 @@ if(WITH_DOC) MESSAGE(FATAL_ERROR "Could not find pandoc for man page generation.") endif(NOT PANDOC_TOOL) - add_custom_target(generate_doc ALL + FIND_PROGRAM(SED_TOOL + NAMES sed + PATHS /bin + /usr/bin + /usr/local/bin) + + if(NOT SED_TOOL) + MESSAGE(FATAL_ERROR "Could not find sed for html generation.") + endif(NOT SED_TOOL) + + file(GLOB MD_FILES "${PROJECT_SOURCE_DIR}/doc/*.md") + + add_custom_target(generate_doc ALL) + add_custom_command(TARGET generate_doc PRE_BUILD COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/README.md -o ${PROJECT_BINARY_DIR}/README.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_for_developers.md -o ${PROJECT_BINARY_DIR}/doc/dlt_for_developers.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_glossary.md -o ${PROJECT_BINARY_DIR}/doc/dlt_glossary.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_offline_logstorage.md -o ${PROJECT_BINARY_DIR}/doc/dlt_offline_logstorage.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_multinode.md -o ${PROJECT_BINARY_DIR}/doc/dlt_multinode.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_extended_network_trace.md -o ${PROJECT_BINARY_DIR}/doc/dlt_extended_network_trace.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_filetransfer.md -o ${PROJECT_BINARY_DIR}/doc/dlt_filetransfer.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_kpi.md -o ${PROJECT_BINARY_DIR}/doc/dlt_kpi.html - COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${PROJECT_SOURCE_DIR}/doc/dlt_cdh.md -o ${PROJECT_BINARY_DIR}/doc/dlt_cdh.html) + COMMAND ${SED_TOOL} -i 's|\.md|\.html|g' ${PROJECT_BINARY_DIR}/README.html) + foreach(FILE ${MD_FILES}) + get_filename_component(FILENAME ${FILE} NAME) + string(REPLACE ".md" ".html" HTML_FILE ${FILENAME}) + add_custom_command(TARGET generate_doc PRE_BUILD + COMMAND ${PANDOC_TOOL} -s -f markdown -t html5 ${FILE} -o ${PROJECT_BINARY_DIR}/doc/${HTML_FILE} + COMMAND ${SED_TOOL} -i 's|\.md|\.html|g' ${PROJECT_BINARY_DIR}/doc/${HTML_FILE}) + endforeach() # Doxygen - find_package(Doxygen) + find_package(Doxygen REQUIRED) configure_file(${PROJECT_SOURCE_DIR}/doc/doxygen.cfg.cmake ${PROJECT_BINARY_DIR}/doc/doxygen.cfg @ONLY) @@ -59,7 +72,7 @@ if(WITH_DOC) add_custom_target (doc-manuals ALL COMMAND mkdir -p ${PROJECT_BINARY_DIR}/doc/manuals COMMAND mkdir -p ${PROJECT_BINARY_DIR}/doc/manuals/images - COMMAND cp ${PROJECT_SOURCE_DIR}/doc/images/* ${PROJECT_BINARY_DIR}/doc/manuals/images + COMMAND cp -r ${PROJECT_SOURCE_DIR}/doc/images/* ${PROJECT_BINARY_DIR}/doc/manuals/images COMMAND ${ASCIIDOC_TOOL} -a TOC1 -o ${PROJECT_BINARY_DIR}/doc/manuals/dlt_design_specification.html ${PROJECT_SOURCE_DIR}/doc/dlt_design_specification.md WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc ) @@ -91,116 +104,56 @@ if(WITH_MAN) set(MAN_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}) set(MAN_BUILD_DIR ${PROJECT_BINARY_DIR}/doc) - set(MD_SRC - ${MAN_SRC_DIR}/dlt.conf.5.md - ${MAN_SRC_DIR}/dlt-system.conf.5.md - ${MAN_SRC_DIR}/dlt_gateway.conf.5.md - ${MAN_SRC_DIR}/dlt-convert.1.md - ${MAN_SRC_DIR}/dlt-sortbytimestamp.1.md - ${MAN_SRC_DIR}/dlt-daemon.1.md - ${MAN_SRC_DIR}/dlt-receive.1.md - ${MAN_SRC_DIR}/dlt-system.1.md - ${MAN_SRC_DIR}/dlt-control.1.md - ${MAN_SRC_DIR}/dlt-logstorage-ctrl.1.md - ${MAN_SRC_DIR}/dlt-passive-node-ctrl.1.md - ${MAN_SRC_DIR}/dlt-adaptor-stdin.1.md - ${MAN_SRC_DIR}/dlt-adaptor-udp.1.md) - - set(MAN_SRC - ${MAN_SRC_DIR}/dlt.conf.5 - ${MAN_SRC_DIR}/dlt-system.conf.5 - ${MAN_SRC_DIR}/dlt_gateway.conf.5 - ${MAN_SRC_DIR}/dlt-convert.1 - ${MAN_SRC_DIR}/dlt-sortbytimestamp.1 - ${MAN_SRC_DIR}/dlt-daemon.1 - ${MAN_SRC_DIR}/dlt-receive.1 - ${MAN_SRC_DIR}/dlt-system.1 - ${MAN_SRC_DIR}/dlt-control.1 - ${MAN_SRC_DIR}/dlt-logstorage-ctrl.1 - ${MAN_SRC_DIR}/dlt-passive-node-ctrl.1 - ${MAN_SRC_DIR}/dlt-adaptor-stdin.1 - ${MAN_SRC_DIR}/dlt-adaptor-udp.1) - - set(MAN_BUILD_SRC - ${MAN_BUILD_DIR}/dlt.conf.5 - ${MAN_BUILD_DIR}/dlt-system.conf.5 - ${MAN_BUILD_DIR}/dlt_gateway.conf.5 - ${MAN_BUILD_DIR}/dlt-convert.1 - ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1 - ${MAN_BUILD_DIR}/dlt-daemon.1 - ${MAN_BUILD_DIR}/dlt-receive.1 - ${MAN_BUILD_DIR}/dlt-system.1 - ${MAN_BUILD_DIR}/dlt-control.1 - ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1 - ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1 - ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1 - ${MAN_BUILD_DIR}/dlt-adaptor-udp.1) - - set(MAN_BUILD_GZ - ${MAN_BUILD_DIR}/dlt.conf.5.gz - ${MAN_BUILD_DIR}/dlt-system.conf.5.gz - ${MAN_BUILD_DIR}/dlt_gateway.conf.5.gz - ${MAN_BUILD_DIR}/dlt-convert.1.gz - ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1.gz - ${MAN_BUILD_DIR}/dlt-daemon.1.gz - ${MAN_BUILD_DIR}/dlt-receive.1.gz - ${MAN_BUILD_DIR}/dlt-system.1.gz - ${MAN_BUILD_DIR}/dlt-control.1.gz - ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz - ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz - ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1.gz - ${MAN_BUILD_DIR}/dlt-adaptor-udp.1.gz) - - add_custom_target(generate_man ALL - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt.conf.5.md -o ${MAN_BUILD_DIR}/dlt.conf.5 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-system.conf.5.md -o ${MAN_BUILD_DIR}/dlt-system.conf.5 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt_gateway.conf.5.md -o ${MAN_BUILD_DIR}/dlt_gateway.conf.5 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-convert.1.md -o ${MAN_BUILD_DIR}/dlt-convert.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-sortbytimestamp.1.md -o ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-daemon.1.md -o ${MAN_BUILD_DIR}/dlt-daemon.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-receive.1.md -o ${MAN_BUILD_DIR}/dlt-receive.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-system.1.md -o ${MAN_BUILD_DIR}/dlt-system.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-control.1.md -o ${MAN_BUILD_DIR}/dlt-control.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-logstorage-ctrl.1.md -o ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-passive-node-ctrl.1.md -o ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-adaptor-stdin.1.md -o ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1 - COMMAND ${PANDOC_TOOL} -s -t man ${MAN_SRC_DIR}/dlt-adaptor-udp.1.md -o ${MAN_BUILD_DIR}/dlt-adaptor-udp.1 - - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt.conf.5 > ${MAN_BUILD_DIR}/dlt.conf.5.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-system.conf.5 > ${MAN_BUILD_DIR}/dlt-system.conf.5.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt_gateway.conf.5 > ${MAN_BUILD_DIR}/dlt_gateway.conf.5.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-convert.1 > ${MAN_BUILD_DIR}/dlt-convert.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1 > ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-daemon.1 > ${MAN_BUILD_DIR}/dlt-daemon.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-receive.1 > ${MAN_BUILD_DIR}/dlt-receive.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-system.1 > ${MAN_BUILD_DIR}/dlt-system.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-control.1 > ${MAN_BUILD_DIR}/dlt-control.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1 > ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1 > ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1 > ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1.gz - COMMAND ${GZIP_TOOL} -c ${MAN_BUILD_DIR}/dlt-adaptor-udp.1 > ${MAN_BUILD_DIR}/dlt-adaptor-udp.1.gz) + file(GLOB MD_SRC "${MAN_SRC_DIR}/*.[1-8].md") + + set(MAN_BUILD_SRC "") + foreach(FILE ${MD_SRC}) + get_filename_component(FILENAME ${FILE} NAME) + string(REPLACE ".md" "" MAN_FILENAME ${FILENAME}) + list(APPEND MAN_BUILD_SRC ${MAN_BUILD_DIR}/${MAN_FILENAME}) + endforeach() + + set(MAN_BUILD_GZ "") + foreach(FILE ${MAN_BUILD_SRC}) + list(APPEND MAN_BUILD_GZ "${FILE}.gz") + endforeach() + + add_custom_target(generate_man ALL) + + set(CNT "0") + list(LENGTH MD_SRC NUMBER_OF_MAN_PAGES) + while(CNT LESS ${NUMBER_OF_MAN_PAGES}) + list(GET MD_SRC ${CNT} SRC_MD_FILE) + list(GET MAN_BUILD_SRC ${CNT} BUILD_MAN_FILE) + list(GET MAN_BUILD_GZ ${CNT} BUILD_MAN_GZ_FILE) + + add_custom_command(TARGET generate_man PRE_BUILD + COMMAND ${PANDOC_TOOL} -s -t man ${SRC_MD_FILE} -o ${BUILD_MAN_FILE} + COMMAND ${GZIP_TOOL} -c ${BUILD_MAN_FILE} > ${BUILD_MAN_GZ_FILE}) + + MATH(EXPR CNT "${CNT}+1") + endwhile() # If user has not set the base dir for man pages, use a default location set(MAN_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/share/man) + set(MAN5_GZ_FILES "") + set(MAN1_GZ_FILES "") + foreach(FILE ${MAN_BUILD_GZ}) + if(${FILE} MATCHES "(\.1\.gz)$") + list(APPEND MAN1_GZ_FILES ${FILE}) + elseif(${FILE} MATCHES "(\.5\.gz)$") + list(APPEND MAN5_GZ_FILES ${FILE}) + endif() + endforeach() + install(FILES - ${MAN_BUILD_DIR}/dlt.conf.5.gz - ${MAN_BUILD_DIR}/dlt-system.conf.5.gz - ${MAN_BUILD_DIR}/dlt_gateway.conf.5.gz + ${MAN5_GZ_FILES} DESTINATION ${MAN_INSTALL_DIR}/man5 ) install(FILES - ${MAN_BUILD_DIR}/dlt-convert.1.gz - ${MAN_BUILD_DIR}/dlt-sortbytimestamp.1.gz - ${MAN_BUILD_DIR}/dlt-daemon.1.gz - ${MAN_BUILD_DIR}/dlt-receive.1.gz - ${MAN_BUILD_DIR}/dlt-system.1.gz - ${MAN_BUILD_DIR}/dlt-control.1.gz - ${MAN_BUILD_DIR}/dlt-logstorage-ctrl.1.gz - ${MAN_BUILD_DIR}/dlt-passive-node-ctrl.1.gz - ${MAN_BUILD_DIR}/dlt-adaptor-stdin.1.gz - ${MAN_BUILD_DIR}/dlt-adaptor-udp.1.gz + ${MAN1_GZ_FILES} DESTINATION ${MAN_INSTALL_DIR}/man1 ) -endif(WITH_MAN) +endif(WITH_MAN) \ No newline at end of file -- cgit v1.2.1