Skip to content

Commit 46ecf6b

Browse files
committed
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
1 parent 09c263e commit 46ecf6b

File tree

4 files changed

+81
-14
lines changed

4 files changed

+81
-14
lines changed

CMakeLists.txt

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ option(build_app "Example showing how to embed doxygen in an application."
1919
option(build_parse "Parses source code and dumps the dependencies between the code elements." OFF)
2020
option(build_xmlparser "Example showing how to parse doxygen's XML output." OFF)
2121
option(build_search "Build external search tools (doxysearch and doxyindexer)" OFF)
22-
option(build_doc "Build user manual" OFF)
22+
option(build_doc "Build user manual (HTML and PDF)" OFF)
23+
option(build_doc_chm "Build user manual (CHM)" OFF)
2324
option(use_sqlite3 "Add support for sqlite3 output [experimental]." OFF)
2425
option(use_libclang "Add support for libclang parsing." OFF)
2526
option(win_static "Link with /MT in stead of /MD on windows" OFF)
@@ -160,6 +161,16 @@ add_subdirectory(qtools)
160161
add_subdirectory(vhdlparser)
161162
add_subdirectory(src)
162163

164+
if (build_doc_chm)
165+
if (WIN32)
166+
find_package(HTMLHelp REQUIRED)
167+
set(build_doc ON)
168+
else ()
169+
message(WARNING "CHM documentation genetration not supported for this platform, ignoring setting.")
170+
set(build_doc_chm OFF)
171+
endif ()
172+
endif ()
173+
163174
if (build_doc)
164175
add_subdirectory(examples)
165176
add_subdirectory(doc)

doc/CMakeLists.txt

Lines changed: 47 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,6 @@ else()
2727
# doxygen project variables are unknown so look for doxygen in PATH
2828
find_package(Doxygen)
2929
endif()
30-
#
31-
# set output directory for some extra HTML files
32-
#
33-
file(STRINGS Doxyfile DOXY_HTML_OUTPUT REGEX "HTML_OUTPUT.*")
34-
string(LENGTH "${DOXY_HTML_OUTPUT}" DOXY_HTML_OUTPUT_LEN)
35-
if (${DOXY_HTML_OUTPUT_LEN})
36-
string(REGEX REPLACE ".*HTML_OUTPUT *= *\([^ ]*\)" "\\1" DOXY_HTML_OUTPUT ${DOXY_HTML_OUTPUT})
37-
else()
38-
set(DOXY_HTML_OUTPUT "html")
39-
endif()
40-
set(PROJECT_BINARY_HTML_DIR ${PROJECT_BINARY_DIR}/${DOXY_HTML_OUTPUT}/)
4130

4231
set(DOC_INSTALL_DIR "share/doc/packages/doxygen" CACHE STRING "Relative path where to install the documentation")
4332
set(DOC_FILES
@@ -96,7 +85,15 @@ set(DOC_FILES
9685
maintainers.txt
9786
translator.py
9887
smile.png
88+
doxygen_logo.gif
89+
doxygen_logo_low.gif
90+
)
91+
92+
if (build_doc_chm)
93+
set(DOC_FILES_CHM
94+
Doxyfile_chm
9995
)
96+
endif ()
10097
file(GLOB LANG_FILES "${TOP}/src/translator_??.h")
10198

10299
file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/man
@@ -117,6 +114,15 @@ set_source_files_properties(${PROJECT_BINARY_DIR}/doc/${f} PROPERTIES GENERATED
117114
list(APPEND OUT_DOC_FILES "${PROJECT_BINARY_DIR}/doc/${f}")
118115
endforeach()
119116

117+
foreach (f ${DOC_FILES_CHM})
118+
add_custom_command(OUTPUT ${PROJECT_BINARY_DIR}/doc/${f}
119+
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/${f} ${PROJECT_BINARY_DIR}/doc/
120+
DEPENDS ${CMAKE_SOURCE_DIR}/doc/${f}
121+
)
122+
set_source_files_properties(${PROJECT_BINARY_DIR}/doc/${f} PROPERTIES GENERATED 1)
123+
list(APPEND OUT_DOC_CHM_FILES "${PROJECT_BINARY_DIR}/doc/${f}")
124+
endforeach()
125+
120126
configure_file(${CMAKE_SOURCE_DIR}/doc/manual.sty ${PROJECT_BINARY_DIR}/doc/manual.sty)
121127
configure_file(${CMAKE_SOURCE_DIR}/doc/doxygen_manual.tex ${PROJECT_BINARY_DIR}/doc/doxygen_manual.tex)
122128
configure_file(${CMAKE_SOURCE_DIR}/doc/doxygen.1 ${PROJECT_BINARY_DIR}/man/doxygen.1)
@@ -165,8 +171,6 @@ add_custom_target(doxygen_pdf
165171
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/latex
166172
)
167173
add_custom_target(docs
168-
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo.gif ${PROJECT_BINARY_HTML_DIR}
169-
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo_low.gif ${PROJECT_BINARY_HTML_DIR}
170174
DEPENDS ${PROJECT_BINARY_DIR}/man/doxygen.1
171175
${PROJECT_BINARY_DIR}/man/doxywizard.1
172176
${PROJECT_BINARY_DIR}/man/doxysearch.1
@@ -175,6 +179,29 @@ add_custom_target(docs
175179
VERBATIM
176180
)
177181

182+
# return status of ${HTML_HELP_COMPILER} is not correct, so we have to do a trick with an "or" statement
183+
# output is redirected to "nul" as we are on windows no problem
184+
if (build_doc_chm)
185+
add_custom_target(docs_chm
186+
COMMENT "Generating CHM documentation."
187+
COMMAND ${CMAKE_COMMAND} -E env VERSION=${VERSION} HTML_HELP_COMPILER=${HTML_HELP_COMPILER} ${DOXYGEN_EXECUTABLE} Doxyfile_chm
188+
COMMAND ${CMAKE_COMMAND} -E copy_directory ${PROJECT_BINARY_DIR}/html/examples ${PROJECT_BINARY_DIR}/chm/examples
189+
COMMAND ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/chm/index.hhp ${PROJECT_BINARY_DIR}/chm/doxygen_manual.hhp
190+
COMMAND ${CMAKE_COMMAND} -E echo "import os" > ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py
191+
COMMAND ${CMAKE_COMMAND} -E echo "for root, dirs, files in os.walk('examples'):" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py
192+
COMMAND ${CMAKE_COMMAND} -E echo " for file in files:" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py
193+
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
194+
COMMAND ${CMAKE_COMMAND} -E echo " print(os.path.join(root, file))" >> ${PROJECT_BINARY_DIR}/chm/doxygen_manual_examples_chm.py
195+
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
196+
COMMAND ${CMAKE_COMMAND} -E chdir ${PROJECT_BINARY_DIR}/chm "${HTML_HELP_COMPILER}" doxygen_manual.hhp || echo > nul
197+
DEPENDS ${PROJECT_BINARY_DIR}/doc/language.doc ${PROJECT_BINARY_DIR}/doc/config.doc
198+
DEPENDS ${OUT_DOC_FILES}
199+
DEPENDS ${OUT_DOC_CHM_FILES}
200+
DEPENDS examples
201+
DEPENDS doxygen
202+
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc/
203+
)
204+
endif ()
178205
################################################################################
179206
install(FILES
180207
"${PROJECT_BINARY_DIR}/man/doxygen.1"
@@ -189,6 +216,13 @@ install(FILES
189216
DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}"
190217
)
191218

219+
if (build_doc_chm)
220+
install(FILES
221+
"${PROJECT_BINARY_DIR}/chm/doxygen_manual.chm"
222+
DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}"
223+
)
224+
endif ()
225+
192226
install(DIRECTORY
193227
"${PROJECT_BINARY_DIR}/html"
194228
DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}"

doc/Doxyfile

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,8 @@ PDF_HYPERLINKS = YES
5050
USE_PDFLATEX = YES
5151
STRIP_CODE_COMMENTS = NO
5252
HTML_STYLESHEET = doxygen_manual.css
53+
HTML_EXTRA_FILES = doxygen_logo.gif
54+
HTML_EXTRA_FILES += doxygen_logo_low.gif
5355
ALIASES = LaTeX="\f$\mbox{\LaTeX}\f$"
5456
ALIASES += TeX="\f$\mbox{\TeX}\f$"
5557
LATEX_BATCHMODE = YES

doc/Doxyfile_chm

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#
2+
# Copyright (C) 1997-2019 by Dimitri van Heesch.
3+
#
4+
# Permission to use, copy, modify, and distribute this software and its
5+
# documentation under the terms of the GNU General Public License is hereby
6+
# granted. No representations are made about the suitability of this software
7+
# for any purpose. It is provided "as is" without express or implied warranty.
8+
# See the GNU General Public License for more details.
9+
#
10+
# Documents produced by Doxygen are derivative works derived from the
11+
# input used in their production; they are not affected by this license.
12+
13+
@INCLUDE = Doxyfile
14+
GENERATE_LATEX = NO
15+
HTML_OUTPUT = chm
16+
GENERATE_HTMLHELP = YES
17+
GENERATE_TREEVIEW = NO
18+
HHC_LOCATION = "$(HTML_HELP_COMPILER)"
19+
CHM_FILE = index.chm
20+
BINARY_TOC = YES

0 commit comments

Comments
 (0)