Permalink
Browse files

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]
  • Loading branch information...
groleo authored and Dimitri van Heesch committed Jun 16, 2015
1 parent 1989a49 commit 3c4a1ea2ee56f2604c2277f13737d53b3a0b0353
Showing with 167 additions and 85 deletions.
  1. +0 −2 .gitignore
  2. +2 −0 .travis.yml
  3. +1 −3 CMakeLists.txt
  4. +1 −1 cmake/run_translator.cmake
  5. +1 −1 cmake/version.cmake
  6. +0 −1 doc/.gitignore
  7. +153 −69 doc/CMakeLists.txt
  8. +2 −2 doc/doxygen.1
  9. +2 −1 doc/doxygen_manual.tex
  10. +1 −1 doc/doxyindexer.1
  11. +1 −1 doc/doxysearch.1
  12. +1 −1 doc/doxywizard.1
  13. +2 −2 doc/manual.sty
@@ -13,5 +13,3 @@
/doxygen_docs
/doxygen.tag
@@ -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
@@ -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")
@@ -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
@@ -1,2 +1,2 @@
file (STRINGS "${SOURCE}/VERSION" VERSION)
file (STRINGS "${TOP}/VERSION" VERSION)
set(ENV{VERSION} "${VERSION}")
@@ -1,2 +1 @@
*.bak
mailto.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)
@@ -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).
@@ -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}
@@ -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
@@ -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
@@ -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
@@ -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{}{}}

0 comments on commit 3c4a1ea

Please sign in to comment.