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]

1 files changed, 153 insertions, 69 deletions

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 3a5d682..709121e 100644
--- 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)