doc: generate Doxygen's documentation.

* use configure_files to avoid different $ semantics when COMMAND lines are expanded in build files. ($$var vs. \$var) * nmake/gmake no longer needed by cmake, when building doc. * explicitly copy doc files into build directory to make it clear what files each build stage uses. Documentation can be built with: mkdir build/ && cd $_ cmake -Dbuild_doc=1 .. # add -G"NMake Makefiles" for nmake make docs # this builds doxygen first v3: replace file(COPY) with proper generated file tagging. v2: Remove option to build documentation independently from doxygen. tested on linux(gmake) and windows(nmake) [thanks albert]
doxygen · Jul 18, 2015 · 3c4a1ea · 3c4a1ea
1 parent 1989a49
commit 3c4a1ea
Show file tree

Hide file tree

Showing 13 changed files with 167 additions and 85 deletions.
diff --git a/.gitignore b/.gitignore
@@ -13,5 +13,3 @@
 
 /doxygen_docs
 /doxygen.tag
-
-
diff --git a/.travis.yml b/.travis.yml
@@ -2,6 +2,7 @@ language: cpp
 compiler:
   - gcc
 before_install:
+    - sudo add-apt-repository ppa:texlive-backports/ppa -qq
     - sudo apt-get update -qq
     - sudo apt-get install -qq  texlive texlive-extra-utils texlive-latex-extra libxml2-utils
     - wget -qO- http://www.cmake.org/files/v3.1/cmake-3.1.0-Linux-x86_64.tar.gz | tar xvz
@@ -12,3 +13,4 @@ script:
     - ../cmake-3.1.0-Linux-x86_64/bin/cmake -G "Unix Makefiles" -Dbuild_doc=ON -Dbuild_wizard=ON ..
     - make
     - make tests
+    - make docs
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -26,7 +26,7 @@ option(english_only    "Only compile in support for the English language" OFF)
 option(force_qt4       "Forces doxywizard to build using Qt4 even if Qt5 is installed" OFF)
 
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
-set(SOURCE "${CMAKE_SOURCE_DIR}")
+set(TOP "${CMAKE_SOURCE_DIR}")
 include(version)
 
 set(sqlite3  "0" CACHE INTERNAL "used in settings.h")
@@ -67,8 +67,6 @@ include_directories(${ICONV_INCLUDE_DIR})
 
 
 #set(DOXYDOCS ${CMAKE_SOURCE_DIR}/doc CACHE INTERNAL "Path to doxygen docs")
-set(DOC_INSTALL_DIR "share/doc/packages/doxygen" CACHE STRING "Relative path where to install the documentation")
-set(EXAMPLE_DIR ${CMAKE_SOURCE_DIR}/examples)
 set(DOXYDOCS ${PROJECT_BINARY_DIR}/doc)
 set(ENV{DOXYGEN_DOCDIR} ${DOXYDOCS})
 set(GENERATED_SRC "${CMAKE_BINARY_DIR}/generated_src" CACHE INTERNAL "Stores generated files")

diff --git a/cmake/run_translator.cmake b/cmake/run_translator.cmake
@@ -1,4 +1,4 @@
-include(${SOURCE}/cmake/version.cmake)
+include(${TOP}/cmake/version.cmake)
 find_program(PYTHON NAMES python)
 execute_process(
     COMMAND ${PYTHON} ${CMAKE_SOURCE_DIR}/translator.py

diff --git a/cmake/version.cmake b/cmake/version.cmake
@@ -1,2 +1,2 @@
-file (STRINGS "${SOURCE}/VERSION" VERSION)
+file (STRINGS "${TOP}/VERSION" VERSION)
 set(ENV{VERSION} "${VERSION}")
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -1,2 +1 @@
 *.bak
-mailto.txt
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -1,89 +1,173 @@
+# vim:ts=4:sw=4:expandtab:autoindent:
+#
+# Copyright (C) 1997-2015 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.
+
 if (build_doc)
 
+include (${TOP}/cmake/version.cmake)
+string(TIMESTAMP DATE "%d-%m-%Y")
+
+find_package(PythonInterp REQUIRED)
 find_program(EPSTOPDF NAMES epstopdf )
-find_program(SED NAMES sed )
-find_program(MAKE NAMES make gmake nmake )
+find_program(PDFLATEX NAMES pdflatex )
+find_program(MAKEINDEX NAMES makeindex )
+
+if (doxygen_BINARY_DIR)
+    set(DOXYGEN_EXECUTABLE ${doxygen_BINARY_DIR}/bin/doxygen)
+else()
+    # when building only the doxygen_doc, from the doc/ directory, the
+    # doxygen project variables are unknown so look for doxygen in PATH
+    find_package(Doxygen)
+endif()
 
-file(GLOB DOC_FILES "*")
-file(GLOB LANG_FILES "${CMAKE_SOURCE_DIR}/src/translator_??.h")
+set(DOC_INSTALL_DIR "share/doc/packages/doxygen" CACHE STRING "Relative path where to install the documentation")
+set(EXAMPLE_DIR ${TOP}/examples)
+set(DOC_FILES
+        arch.doc
+        archoverview.eps
+        archoverview.gif
+        autolink.doc
+        changelog.doc
+        commands.doc
+        custcmd.doc
+        customize.doc
+        diagrams.doc
+        docblocks.doc
+        Doxyfile
+        doxygen_manual.css
+        doxygen_usage.doc
+        doxywizard_expert.png
+        doxywizard.gif
+        doxywizard_main.png
+        doxywizard_menu.png
+        doxywizard_page1.png
+        doxywizard_page2.png
+        doxywizard_page3.png
+        doxywizard_page4.png
+        doxywizard_usage.doc
+        external.doc
+        extsearch.doc
+        extsearch_flow.dot
+        extsearch_flow.eps
+        extsearch_flow.png
+        faq.doc
+        features.doc
+        formulas.doc
+        grouping.doc
+        htmlcmds.doc
+        index.doc
+        index.hhp.txt
+        infoflow.eps
+        infoflow.fig
+        infoflow.png
+        install.doc
+        install_prefix
+        lists.doc
+        markdown.doc
+        output.doc
+        perlmod.doc
+        perlmod_tree.doc
+        preprocessing.doc
+        searching.doc
+        starting.doc
+        trouble.doc
+        xmlcmds.doc
+        language.tpl
+        maintainers.txt
+        translator.py
+)
+file(GLOB LANG_FILES "${TOP}/src/translator_??.h")
 
 file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/man)
 file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/src)
-file(COPY ${CMAKE_SOURCE_DIR}/src/translator.h DESTINATION ${PROJECT_BINARY_DIR}/src)
-file(COPY ${CMAKE_SOURCE_DIR}/src/translator_adapter.h DESTINATION ${PROJECT_BINARY_DIR}/src)
-file(COPY ${LANG_FILES} DESTINATION ${PROJECT_BINARY_DIR}/src)
-file(COPY ${CMAKE_SOURCE_DIR}/VERSION DESTINATION ${PROJECT_BINARY_DIR})
-
-# copy all doc files
-add_custom_target(copy_docs)
-foreach(doc_file ${DOC_FILES})
-  add_custom_command(TARGET copy_docs PRE_BUILD
-                     COMMAND ${CMAKE_COMMAND} -E
-                         copy ${doc_file} ${DOXYDOCS})
+file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/doc)
+
+file(COPY ${TOP}/VERSION                  DESTINATION ${PROJECT_BINARY_DIR}/)
+file(COPY ${TOP}/src/translator.h         DESTINATION ${PROJECT_BINARY_DIR}/src/)
+file(COPY ${TOP}/src/translator_adapter.h DESTINATION ${PROJECT_BINARY_DIR}/src/)
+file(COPY ${LANG_FILES}                   DESTINATION ${PROJECT_BINARY_DIR}/src/)
+file(COPY ${EXAMPLE_DIR}                  DESTINATION ${PROJECT_BINARY_DIR}/)
+
+foreach (f  ${DOC_FILES})
+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_FILES "${PROJECT_BINARY_DIR}/doc/${f}")
 endforeach()
 
-add_custom_target(docs
-	COMMENT "Generating documentation in ${DOXYDOCS}"
-	COMMAND ${EXECUTABLE_OUTPUT_PATH}/doxygen
-	COMMAND ${CMAKE_COMMAND} -E remove_directory ../latex/refman.tex
-	COMMAND ${CMAKE_COMMAND} -E copy doxygen_logo.gif ../html
-	COMMAND ${CMAKE_COMMAND} -E copy doxygen_logo_low.gif ../html
-	COMMAND ${CMAKE_COMMAND} -E copy Makefile.latex ../latex/Makefile
-	COMMAND ${SED} -e "s/\$VERSION/${VERSION}/g" doxygen_manual.tex > ../latex/doxygen_manual.tex
-	COMMAND ${SED} -e "s/\$VERSION/${VERSION}/g" manual.sty > ../latex/manual.sty
-	COMMAND ${EPSTOPDF} doxygen_logo.eps --outfile=../latex/doxygen_logo.pdf
-        COMMAND ${MAKE} -C ../latex 
-#> latex_out.txt
-	DEPENDS doxygen copy_docs ${PROJECT_BINARY_DIR}/doc/language.doc config.doc examples
-                "${PROJECT_BINARY_DIR}/man/doxygen.1"
-                "${PROJECT_BINARY_DIR}/man/doxywizard.1"
-                "${PROJECT_BINARY_DIR}/man/doxysearch.1"
-                "${PROJECT_BINARY_DIR}/man/doxyindexer.1"
-	WORKING_DIRECTORY ${DOXYDOCS}
-	VERBATIM
-	)
-
-# language.doc
-add_custom_command(
-        COMMAND ${CMAKE_COMMAND} "-DSOURCE=${CMAKE_SOURCE_DIR}" -P ${CMAKE_SOURCE_DIR}/cmake/run_translator.cmake
-	DEPENDS ${DOXYDOCS}/translator.py
-	DEPENDS maintainers.txt language.tpl translator.py
-	OUTPUT ${PROJECT_BINARY_DIR}/doc/language.doc
-	WORKING_DIRECTORY ${DOXYDOCS}
-)
-set_source_files_properties(${DOXYDOCS}/language.doc PROPERTIES GENERATED 1)
-
-# config.doc
-add_custom_command(
-	COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_SOURCE_DIR}/src/configgen.py -doc ${CMAKE_SOURCE_DIR}/src/config.xml > config.doc
-	DEPENDS ${CMAKE_SOURCE_DIR}/src/config.xml ${CMAKE_SOURCE_DIR}/src/configgen.py
-	OUTPUT config.doc
-	WORKING_DIRECTORY ${DOXYDOCS}
-)
-set_source_files_properties(${DOXYDOCS}/config.doc PROPERTIES GENERATED 1)
-
-string(TIMESTAMP TODAY "%d-%m-%Y")
+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)
+configure_file(${CMAKE_SOURCE_DIR}/doc/doxywizard.1       ${PROJECT_BINARY_DIR}/man/doxywizard.1)
+configure_file(${CMAKE_SOURCE_DIR}/doc/doxysearch.1       ${PROJECT_BINARY_DIR}/man/doxysearch.1)
+configure_file(${CMAKE_SOURCE_DIR}/doc/doxyindexer.1      ${PROJECT_BINARY_DIR}/man/doxyindexer.1)
 
+# doc/language.doc (see tag Doxyfile:INPUT)
 add_custom_command(
-	COMMAND ${SED} -e "s/DATE/${TODAY}/g" -e "s/VERSION/${VERSION}/g" doxygen.1 > "${PROJECT_BINARY_DIR}/man/doxygen.1"
-        OUTPUT "${PROJECT_BINARY_DIR}/man/doxygen.1"
+        COMMAND ${PYTHON_EXECUTABLE} translator.py
+        DEPENDS ${PROJECT_BINARY_DIR}/doc/maintainers.txt ${PROJECT_BINARY_DIR}/doc/language.tpl ${PROJECT_BINARY_DIR}/doc/translator.py
+        OUTPUT language.doc
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc
 )
+set_source_files_properties(language.doc PROPERTIES GENERATED 1)
 
+# doc/config.doc (see tag Doxyfile:INPUT)
 add_custom_command(
-	COMMAND ${SED} -e "s/DATE/${TODAY}/g" -e "s/VERSION/${VERSION}/g" doxywizard.1 > "${PROJECT_BINARY_DIR}/man/doxywizard.1"
-        OUTPUT "${PROJECT_BINARY_DIR}/man/doxywizard.1"
+        COMMAND ${PYTHON_EXECUTABLE}  ${TOP}/src/configgen.py -doc ${TOP}/src/config.xml > config.doc
+        DEPENDS ${TOP}/src/config.xml ${TOP}/src/configgen.py
+        OUTPUT config.doc
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc/
 )
-
-add_custom_command(
-	COMMAND ${SED} -e "s/DATE/${TODAY}/g" -e "s/VERSION/${VERSION}/g" doxysearch.1 > "${PROJECT_BINARY_DIR}/man/doxysearch.1"
-        OUTPUT "${PROJECT_BINARY_DIR}/man/doxysearch.1"
+set_source_files_properties(config.doc PROPERTIES GENERATED 1)
+################################################################################
+add_custom_target(run_doxygen
+        COMMENT "Generating Latex and HTML documentation."
+        COMMAND ${DOXYGEN_EXECUTABLE}
+        DEPENDS ${PROJECT_BINARY_DIR}/doc/language.doc ${PROJECT_BINARY_DIR}/doc/config.doc ${OUT_DOC_FILES}
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc/
 )
+if (doxygen_BINARY_DIR)
+    # building from project `doxygen'
+    add_dependencies(run_doxygen
+       doxygen
+    )
+endif()
 
-add_custom_command(
-	COMMAND ${SED} -e "s/DATE/${TODAY}/g" -e "s/VERSION/${VERSION}/g" doxyindexer.1 > "${PROJECT_BINARY_DIR}/man/doxyindexer.1"
-        OUTPUT "${PROJECT_BINARY_DIR}/man/doxyindexer.1"
+add_custom_target(doxygen_pdf
+        COMMENT "Generating Doxygen Manual PDF."
+        COMMAND ${CMAKE_COMMAND} -E remove_directory refman.tex
+        COMMAND ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/doc/doxygen_manual.tex  .
+        COMMAND ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/doc/manual.sty  .
+        COMMAND ${EPSTOPDF} ${CMAKE_SOURCE_DIR}/doc/doxygen_logo.eps --outfile=doxygen_logo.pdf
+        COMMAND ${PDFLATEX}  doxygen_manual.tex
+        COMMAND ${MAKEINDEX} doxygen_manual.idx
+        COMMAND ${PDFLATEX}  doxygen_manual.tex
+        DEPENDS run_doxygen
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/latex
 )
-
+add_custom_target(docs
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo.gif      ${PROJECT_BINARY_DIR}/html/
+        COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/doc/doxygen_logo_low.gif  ${PROJECT_BINARY_DIR}/html/
+        DEPENDS ${PROJECT_BINARY_DIR}/man/doxygen.1
+                ${PROJECT_BINARY_DIR}/man/doxywizard.1
+                ${PROJECT_BINARY_DIR}/man/doxysearch.1
+                ${PROJECT_BINARY_DIR}/man/doxyindexer.1
+                doxygen_pdf
+        VERBATIM
+        )
+
+################################################################################
 install(FILES
         "${PROJECT_BINARY_DIR}/man/doxygen.1"
         "${PROJECT_BINARY_DIR}/man/doxywizard.1"
@@ -102,4 +186,4 @@ install(DIRECTORY
         DESTINATION "${CMAKE_INSTALL_PREFIX}/${DOC_INSTALL_DIR}"
 )
 
-endif()
+endif(build_doc)
diff --git a/doc/doxygen.1 b/doc/doxygen.1
@@ -1,4 +1,4 @@
-.TH DOXYGEN "1" "DATE" "doxygen VERSION" "User Commands"
+.TH DOXYGEN "1" "@DATE@" "doxygen @VERSION@" "User Commands"
 .SH NAME
 doxygen \- documentation system for various programming languages
 .SH DESCRIPTION
@@ -45,6 +45,6 @@ doxygen \fB\-e\fR rtf extensionsFile
 If \fB\-s\fR is specified the comments in the config file will be omitted.
 If configName is omitted `Doxyfile' will be used as a default.
 .SH AUTHOR
-Doxygen version VERSION, Copyright Dimitri van Heesch 1997-2015
+Doxygen version @VERSION@, Copyright Dimitri van Heesch 1997-2015
 .SH SEE ALSO
 doxywizard(1).
diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex
@@ -12,6 +12,7 @@
 % Documents produced by Doxygen are derivative works derived from the
 % input used in their production; they are not affected by this license.
 
+\batchmode
 \documentclass{book}
 \usepackage[a4paper,left=2.5cm,right=2.5cm,top=2.5cm,bottom=2.5cm]{geometry}
 \usepackage{makeidx}
@@ -72,7 +73,7 @@
 \begin{titlepage}
 \includegraphics[width=\textwidth]{doxygen_logo}
 \begin{center}
-Manual for version $VERSION\\[2ex]
+Manual for version @VERSION@\\[2ex]
 Written by Dimitri van Heesch\\[2ex]
 \copyright 1997-\thisyear
 \end{center}

diff --git a/doc/doxyindexer.1 b/doc/doxyindexer.1
@@ -1,4 +1,4 @@
-.TH DOXYINDEXER "1" "DATE" "doxyindexer VERSION" "User Commands"
+.TH DOXYINDEXER "1" "@DATE@" "doxyindexer @VERSION@" "User Commands"
 .SH NAME
 doxyindexer \- creates a search index from raw search data
 .SH SYNOPSIS

diff --git a/doc/doxysearch.1 b/doc/doxysearch.1
@@ -1,4 +1,4 @@
-.TH DOXYSEARCH "1" "DATE" "doxysearch.cgi VERSION" "User Commands"
+.TH DOXYSEARCH "1" "@DATE@" "doxysearch.cgi @VERSION@" "User Commands"
 .SH NAME
 doxysearch.cgi \- search engine used for searching in doxygen documentation.
 .SH SYNOPSIS

diff --git a/doc/doxywizard.1 b/doc/doxywizard.1
@@ -1,4 +1,4 @@
-.TH DOXYWIZARD "1" "DATE" "doxywizard VERSION" "User Commands"
+.TH DOXYWIZARD "1" "@DATE@" "doxywizard @VERSION@" "User Commands"
 .SH NAME
 doxywizard \- a tool to configure and run doxygen on your source files
 .SH SYNOPSIS

diff --git a/doc/manual.sty b/doc/manual.sty
@@ -26,8 +26,8 @@
 \fancyhead[RO]{\fancyplain{}{\bfseries\thepage}}
 \fancyfoot[LE]{\fancyplain{}{}}
 \fancyfoot[CE]{\fancyplain{}{}}
-\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize Generated by Doxygen $VERSION }}
-\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize Generated by Doxygen $VERSION }}
+\fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize Generated by Doxygen @VERSION@ }}
+\fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize Generated by Doxygen @VERSION@ }}
 \fancyfoot[CO]{\fancyplain{}{}}
 \fancyfoot[RO]{\fancyplain{}{}}