From 3c4a1ea2ee56f2604c2277f13737d53b3a0b0353 Mon Sep 17 00:00:00 2001 From: Adrian Negreanu Date: Tue, 16 Jun 2015 14:50:21 +0300 Subject: 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] --- .gitignore | 2 - .travis.yml | 2 + CMakeLists.txt | 4 +- cmake/run_translator.cmake | 2 +- cmake/version.cmake | 2 +- doc/.gitignore | 1 - doc/CMakeLists.txt | 222 +++++++++++++++++++++++++++++++-------------- doc/doxygen.1 | 4 +- doc/doxygen_manual.tex | 3 +- doc/doxyindexer.1 | 2 +- doc/doxysearch.1 | 2 +- doc/doxywizard.1 | 2 +- doc/manual.sty | 4 +- 13 files changed, 167 insertions(+), 85 deletions(-) diff --git a/.gitignore b/.gitignore index 3e575a1..21ebe47 100644 --- a/.gitignore +++ b/.gitignore @@ -13,5 +13,3 @@ /doxygen_docs /doxygen.tag - - diff --git a/.travis.yml b/.travis.yml index e45a202..2444e79 100644 --- 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 index 44f493c..dcb329b 100644 --- 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 index 618bb82..d1b187c 100644 --- 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 index 48de7b2..b59aa29 100644 --- 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 index d1d1371..751553b 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,2 +1 @@ *.bak -mailto.txt 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) diff --git a/doc/doxygen.1 b/doc/doxygen.1 index 6861c22..1deb7b6 100644 --- 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 index 5a3c372..84a792d 100644 --- 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 index 7b7a298..ae4b282 100644 --- 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 index da9ae05..a00124f 100644 --- 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 index e3f23c0..9f57701 100644 --- 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 index 254aa03..80fbda6 100644 --- 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{}{}} -- cgit v0.12