From 46ecf6bf78f1c0d4aa140db74847fafc5613dfe7 Mon Sep 17 00:00:00 2001 From: albert-github Date: Sun, 11 Aug 2019 18:36:18 +0200 Subject: Generating doxygen's documentation in CHM format Until now the chm format of the doxygen documentation was generated by a separate script, this is now integrated in the CMake procedure. - option -Dbuild_doc_chm to enable the possibility to generate the CHM documentation (only works for windows) - procedure is as follows - generate the base documentation for the CHM output - copy the documentation of the examples to the tree with the base CHM output (cannot use it from its default place due to the fact that in the next face the first page of the CHM file will be wrong - add the html, png, css and gif files of the examples to the so called hhp file (has to happen during runtime, hence a small python script, created inline so there is no extra file in the source tree) - create the resulting doxygen_manual.chm Some improvements during the process - the html files of the examples are added so that the full documentation of the examples is accessible and not just the top pages of the examples - keep the index terms of base chm file (mostly the commands and configuration parameters) - see to it that the doxygen logo is copied by doxygen and not by means of cmake --- CMakeLists.txt | 13 +++++++++++- doc/CMakeLists.txt | 60 ++++++++++++++++++++++++++++++++++++++++++------------ doc/Doxyfile | 2 ++ doc/Doxyfile_chm | 20 ++++++++++++++++++ 4 files changed, 81 insertions(+), 14 deletions(-) create mode 100644 doc/Doxyfile_chm diff --git a/CMakeLists.txt b/CMakeLists.txt index 2621844..16e70ff 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -19,7 +19,8 @@ option(build_app "Example showing how to embed doxygen in an application." option(build_parse "Parses source code and dumps the dependencies between the code elements." OFF) option(build_xmlparser "Example showing how to parse doxygen's XML output." OFF) option(build_search "Build external search tools (doxysearch and doxyindexer)" OFF) -option(build_doc "Build user manual" OFF) +option(build_doc "Build user manual (HTML and PDF)" OFF) +option(build_doc_chm "Build user manual (CHM)" OFF) option(use_sqlite3 "Add support for sqlite3 output [experimental]." OFF) option(use_libclang "Add support for libclang parsing." OFF) option(win_static "Link with /MT in stead of /MD on windows" OFF) @@ -160,6 +161,16 @@ add_subdirectory(qtools) add_subdirectory(vhdlparser) add_subdirectory(src) +if (build_doc_chm) + if (WIN32) + find_package(HTMLHelp REQUIRED) + set(build_doc ON) + else () + message(WARNING "CHM documentation genetration not supported for this platform, ignoring setting.") + set(build_doc_chm OFF) + endif () +endif () + if (build_doc) add_subdirectory(examples) add_subdirectory(doc) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 7beb485..8dbe8ae 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -27,17 +27,6 @@ else() # doxygen project variables are unknown so look for doxygen in PATH find_package(Doxygen) endif() -# -# set output directory for some extra HTML files -# -file(STRINGS Doxyfile DOXY_HTML_OUTPUT REGEX "HTML_OUTPUT.*") -string(LENGTH "${DOXY_HTML_OUTPUT}" DOXY_HTML_OUTPUT_LEN) -if (${DOXY_HTML_OUTPUT_LEN}) - string(REGEX REPLACE ".*HTML_OUTPUT *= *\([^ ]*\)" "\\1" DOXY_HTML_OUTPUT ${DOXY_HTML_OUTPUT}) -else() - set(DOXY_HTML_OUTPUT "html") -endif() -set(PROJECT_BINARY_HTML_DIR ${PROJECT_BINARY_DIR}/${DOXY_HTML_OUTPUT}/) set(DOC_INSTALL_DIR "share/doc/packages/doxygen" CACHE STRING "Relative path where to install the documentation") set(DOC_FILES @@ -96,7 +85,15 @@ set(DOC_FILES maintainers.txt translator.py smile.png + doxygen_logo.gif + doxygen_logo_low.gif +) + +if (build_doc_chm) + set(DOC_FILES_CHM + Doxyfile_chm ) +endif () file(GLOB LANG_FILES "${TOP}/src/translator_??.h") file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/man @@ -117,6 +114,15 @@ set_source_files_properties(${PROJECT_BINARY_DIR}/doc/${f} PROPERTIES GENERATED list(APPEND OUT_DOC_FILES "${PROJECT_BINARY_DIR}/doc/${f}") endforeach() +foreach (f ${DOC_FILES_CHM}) +add_custom_command(OUTPUT ${PROJECT_BINARY_DIR}/doc/${f} + COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/${f} ${PROJECT_BINARY_DIR}/doc/ + DEPENDS ${CMAKE_SOURCE_DIR}/doc/${f} + ) +set_source_files_properties(${PROJECT_BINARY_DIR}/doc/${f} PROPERTIES GENERATED 1) +list(APPEND OUT_DOC_CHM_FILES "${PROJECT_BINARY_DIR}/doc/${f}") +endforeach() + configure_file(${CMAKE_SOURCE_DIR}/doc/manual.sty ${PROJECT_BINARY_DIR}/doc/manual.sty) configure_file(${CMAKE_SOURCE_DIR}/doc/doxygen_manual.tex ${PROJECT_BINARY_DIR}/doc/doxygen_manual.tex) configure_file(${CMAKE_SOURCE_DIR}/doc/doxygen.1 ${PROJECT_BINARY_DIR}/man/doxygen.1) @@ -165,8 +171,6 @@ add_custom_target(doxygen_pdf WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/latex ) add_custom_target(docs - COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo.gif ${PROJECT_BINARY_HTML_DIR} - COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo_low.gif ${PROJECT_BINARY_HTML_DIR} DEPENDS ${PROJECT_BINARY_DIR}/man/doxygen.1 ${PROJECT_BINARY_DIR}/man/doxywizard.1 ${PROJECT_BINARY_DIR}/man/doxysearch.1 @@ -175,6 +179,29 @@ add_custom_target(docs VERBATIM ) +# return status of ${HTML_HELP_COMPILER} is not correct, so we have to do a trick with an "or" statement +# output is redirected to "nul" as we are on windows no problem +if (build_doc_chm) +add_custom_target(docs_chm + COMMENT "Generating CHM documentation." + COMMAND ${CMAKE_COMMAND} -E env VERSION=${VERSION} HTML_HELP_COMPILER=${HTML_HELP_COMPILER} ${DOXYGEN_EXECUTABLE} Doxyfile_chm + COMMAND ${CMAKE_COMMAND} -E copy_directory ${PROJECT_BINARY_DIR}/html/examples ${PROJECT_BINARY_DIR}/chm/examples + COMMAND ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/chm/index.hhp ${PROJECT_BINARY_DIR}/chm/doxygen_manual.hhp + COMMAND ${CMAKE_COMMAND} -E echo "import os" > ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py + COMMAND ${CMAKE_COMMAND} -E echo "for root, dirs, files in os.walk('examples'):" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py + COMMAND ${CMAKE_COMMAND} -E echo " for file in files:" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py + COMMAND ${CMAKE_COMMAND} -E echo " if file.endswith('.html') or file.endswith('.png') or file.endswith('.css') or file.endswith('.gif'):" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py + COMMAND ${CMAKE_COMMAND} -E echo " print(os.path.join(root, file))" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py + COMMAND ${CMAKE_COMMAND} -E chdir ${PROJECT_BINARY_DIR}/chm ${PYTHON_EXECUTABLE} ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual.hhp + COMMAND ${CMAKE_COMMAND} -E chdir ${PROJECT_BINARY_DIR}/chm "${HTML_HELP_COMPILER}" doxygen_manual.hhp || echo > nul + DEPENDS ${PROJECT_BINARY_DIR}/doc/language.doc ${PROJECT_BINARY_DIR}/doc/config.doc + DEPENDS ${OUT_DOC_FILES} + DEPENDS ${OUT_DOC_CHM_FILES} + DEPENDS examples + DEPENDS doxygen + WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc/ +) +endif () ################################################################################ install(FILES "${PROJECT_BINARY_DIR}/man/doxygen.1" @@ -189,6 +216,13 @@ install(FILES DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}" ) +if (build_doc_chm) +install(FILES + "${PROJECT_BINARY_DIR}/chm/doxygen_manual.chm" + DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}" +) +endif () + install(DIRECTORY "${PROJECT_BINARY_DIR}/html" DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}" diff --git a/doc/Doxyfile b/doc/Doxyfile index 7697d70..2ff093f 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -50,6 +50,8 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES STRIP_CODE_COMMENTS = NO HTML_STYLESHEET = doxygen_manual.css +HTML_EXTRA_FILES = doxygen_logo.gif +HTML_EXTRA_FILES += doxygen_logo_low.gif ALIASES = LaTeX="\f$\mbox{\LaTeX}\f$" ALIASES += TeX="\f$\mbox{\TeX}\f$" LATEX_BATCHMODE = YES diff --git a/doc/Doxyfile_chm b/doc/Doxyfile_chm new file mode 100644 index 0000000..8fb51a6 --- /dev/null +++ b/doc/Doxyfile_chm @@ -0,0 +1,20 @@ +# +# Copyright (C) 1997-2019 by Dimitri van Heesch. +# +# Permission to use, copy, modify, and distribute this software and its +# documentation under the terms of the GNU General Public License is hereby +# granted. No representations are made about the suitability of this software +# for any purpose. It is provided "as is" without express or implied warranty. +# See the GNU General Public License for more details. +# +# Documents produced by Doxygen are derivative works derived from the +# input used in their production; they are not affected by this license. + +@INCLUDE = Doxyfile + GENERATE_LATEX = NO + HTML_OUTPUT = chm + GENERATE_HTMLHELP = YES + GENERATE_TREEVIEW = NO + HHC_LOCATION = "$(HTML_HELP_COMPILER)" + CHM_FILE = index.chm + BINARY_TOC = YES -- cgit v0.12