summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordbiastoch <dbiastoch@de.adit-jv.com>2021-02-03 15:11:00 +0100
committerSaya Sugiura <39760799+ssugiura@users.noreply.github.com>2021-06-30 10:54:59 +0900
commit5e188475628635f3254484ed506d8abba096d469 (patch)
tree8b011b3e8042887b62b4c53c115d9d495db1e477
parentd3f62e237096e79c215cb728e8105e82c4e6e7dd (diff)
downloadDLT-daemon-5e188475628635f3254484ed506d8abba096d469.tar.gz
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 <dbiastoch@de.adit-jv.com>
-rw-r--r--README.md2
-rw-r--r--doc/CMakeLists.txt179
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