From 301e6ab4c41152cfb791eaf6584abec08a96d652 Mon Sep 17 00:00:00 2001 From: Teemu Murtola Date: Sat, 13 Sep 2014 06:59:28 +0300 Subject: [PATCH] Misc. Doxygen build system improvements - Only generate the installed header list once after CMake is run. It cannot change unless CMake is run again. This wasn't particularly slow earlier either, but now it can be added as a dependency also in the -fast targets without any impact on the behavior. - Do not update the Doxyfile-common each time CMake is run if GMX_COMPACT_DOXYGEN=ON. - Partition the Markdown pages into subdirectories based on the documentation level where they should appear. Exclude things from the documentation based on the directory, not individually. - Use a CMake function to create the various Doxygen targets to remove some duplication. - Some cleanup in the directories.cpp and misc.cpp documentation files. - Some cleanup to use consistent casing throughout CMakeLists.txt. Change-Id: I30de6f36841f25260700ec92284762e989f66507 --- docs/doxygen/CMakeLists.txt | 78 ++++++++++---------- docs/doxygen/Doxyfile-common.cmakein | 1 + docs/doxygen/Doxyfile-user.cmakein | 5 +- docs/doxygen/directories.cpp | 24 ++---- docs/doxygen/{ => lib}/doxygen.md | 9 ++- docs/doxygen/{ => lib}/simd.md | 0 docs/doxygen/{ => lib}/unittesting.md | 0 docs/doxygen/{ => lib}/wrapperbinary.md | 0 docs/doxygen/misc.cpp | 16 +++- docs/doxygen/{ => user}/analysisdata.md | 0 docs/doxygen/{ => user}/analysisframework.md | 0 docs/doxygen/{ => user}/analysistemplate.md | 0 docs/doxygen/{ => user}/codelayout.md | 0 docs/doxygen/{ => user}/mainpage.md | 0 docs/doxygen/{ => user}/selections.md | 0 docs/doxygen/{ => user}/usinglibrary.md | 0 16 files changed, 68 insertions(+), 65 deletions(-) rename docs/doxygen/{ => lib}/doxygen.md (99%) rename docs/doxygen/{ => lib}/simd.md (100%) rename docs/doxygen/{ => lib}/unittesting.md (100%) rename docs/doxygen/{ => lib}/wrapperbinary.md (100%) rename docs/doxygen/{ => user}/analysisdata.md (100%) rename docs/doxygen/{ => user}/analysisframework.md (100%) rename docs/doxygen/{ => user}/analysistemplate.md (100%) rename docs/doxygen/{ => user}/codelayout.md (100%) rename docs/doxygen/{ => user}/mainpage.md (100%) rename docs/doxygen/{ => user}/selections.md (100%) rename docs/doxygen/{ => user}/usinglibrary.md (100%) diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt index 30dbf7cc20..7ffe276de5 100644 --- a/docs/doxygen/CMakeLists.txt +++ b/docs/doxygen/CMakeLists.txt @@ -38,7 +38,7 @@ find_package(Doxygen QUIET) if (DOXYGEN_FOUND) # This logic closely follows that found in FindDoxygen.cmake for dot, # except that the PATH variable is not cached. - FIND_PROGRAM(DOXYGEN_MSCGEN_EXECUTABLE + find_program(DOXYGEN_MSCGEN_EXECUTABLE NAMES mscgen DOC "Message sequence chart renderer tool (http://www.mcternan.me.uk/mscgen/)") if (DOXYGEN_MSCGEN_EXECUTABLE) @@ -61,63 +61,62 @@ if (PYTHONINTERP_FOUND AND NOT PYTHON_VERSION_STRING VERSION_LESS "2.6") set(USE_PYTHON_SCRIPTS ON) endif() -add_custom_target(find-installed-headers +# Create a stamp file whenever cmake is run, as the list of installed files may +# have changed. +set(CONFIGURE_STAMP_FILE ${CMAKE_CURRENT_BINARY_DIR}/cmake-stamp.txt) +file(WRITE ${CONFIGURE_STAMP_FILE} "Stamp for configuration") +# Note that if you relocate this file, you also need to change gmxtree.py. +set(INSTALLED_HEADERS_FILE ${CMAKE_CURRENT_BINARY_DIR}/installed-headers.txt) +add_custom_command(OUTPUT ${INSTALLED_HEADERS_FILE} COMMAND ${CMAKE_COMMAND} -D SRCDIR=${CMAKE_SOURCE_DIR} -D BUILDDIR=${CMAKE_BINARY_DIR} - -D OUTFILE=${CMAKE_CURRENT_BINARY_DIR}/installed-headers.txt + -D OUTFILE=${INSTALLED_HEADERS_FILE} -P ${CMAKE_CURRENT_SOURCE_DIR}/getInstalledHeaders.cmake + DEPENDS ${CONFIGURE_STAMP_FILE} COMMENT "Generating installed headers list" VERBATIM) +add_custom_target(find-installed-headers DEPENDS ${INSTALLED_HEADERS_FILE}) ######################################################################## # Doxygen configuration ######################################################################## if (DOXYGEN_FOUND) - FILE(GLOB NB_KERNEL_DIRS + file(GLOB NB_KERNEL_DIRS ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_*/) - LIST(REMOVE_ITEM NB_KERNEL_DIRS + list(REMOVE_ITEM NB_KERNEL_DIRS ${CMAKE_SOURCE_DIR}/src/gromacs/gmxlib/nonbonded/nb_kernel_c) - FOREACH(NB_KERNEL_DIR ${NB_KERNEL_DIRS}) + foreach (NB_KERNEL_DIR ${NB_KERNEL_DIRS}) SET(NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN "${NB_KERNEL_DIRS_TO_IGNORE_IN_DOXYGEN} \\\n ${NB_KERNEL_DIR}") - ENDFOREACH(NB_KERNEL_DIR) + endforeach() set(DOXYGEN_SECTIONS "") - CONFIGURE_FILE(Doxyfile-common.cmakein Doxyfile-common) - CONFIGURE_FILE(Doxyfile-full.cmakein Doxyfile-full) - CONFIGURE_FILE(Doxyfile-lib.cmakein Doxyfile-lib) - CONFIGURE_FILE(Doxyfile-user.cmakein Doxyfile-user) - CONFIGURE_FILE(Doxyfile-xml.cmakein Doxyfile-xml) - + set(DOXYGEN_EXTRA_SETTINGS "") if (GMX_COMPACT_DOXYGEN) - FILE(APPEND ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile-common - "@INCLUDE = ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact\n") + set(DOXYGEN_EXTRA_SETTINGS "@INCLUDE = ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile-compact") endif() + configure_file(Doxyfile-common.cmakein Doxyfile-common) + configure_file(Doxyfile-full.cmakein Doxyfile-full) + configure_file(Doxyfile-lib.cmakein Doxyfile-lib) + configure_file(Doxyfile-user.cmakein Doxyfile-user) + configure_file(Doxyfile-xml.cmakein Doxyfile-xml) configure_file(RunDoxygen.cmake.cmakein RunDoxygen.cmake @ONLY) gmx_configure_version_file(Doxyfile-version.cmakein Doxyfile-version TARGET doxygen-version) - add_custom_target(doc-full - ${CMAKE_COMMAND} -DDOCTYPE=full -P RunDoxygen.cmake - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating full documentation with Doxygen" VERBATIM) - add_custom_target(doc-lib - ${CMAKE_COMMAND} -DDOCTYPE=lib -P RunDoxygen.cmake - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating library documentation with Doxygen" VERBATIM) - add_custom_target(doc-user - ${CMAKE_COMMAND} -DDOCTYPE=user -P RunDoxygen.cmake - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating public API documentation with Doxygen" VERBATIM) - add_custom_target(doc-xml - ${CMAKE_COMMAND} -DDOCTYPE=xml -P RunDoxygen.cmake - WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Extracting Doxygen documentation to XML" VERBATIM) + + function (add_doxygen_target TARGET TYPE COMMENT) + add_custom_target(${TARGET} + ${CMAKE_COMMAND} -DDOCTYPE=${TYPE} -P RunDoxygen.cmake + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} + COMMENT "${COMMENT}" VERBATIM) + add_dependencies(${TARGET} doxygen-version) + endfunction() + add_doxygen_target(doc-full full "Generating full documentation with Doxygen") + add_doxygen_target(doc-lib lib "Generating library documentation with Doxygen") + add_doxygen_target(doc-user user "Generating public API documentation with Doxygen") + add_doxygen_target(doc-xml xml "Extracting Doxygen documentation to XML") add_custom_target(doc-all) add_dependencies(doc-all doc-full doc-lib doc-user) - add_dependencies(doc-full doxygen-version) - add_dependencies(doc-lib doxygen-version) - add_dependencies(doc-user doxygen-version) - add_dependencies(doc-xml doxygen-version) if (USE_PYTHON_SCRIPTS) # TODO: Consider whether this is the best name and location for this @@ -150,14 +149,17 @@ if (DOXYGEN_FOUND) COMMENT "Generating include dependency graphs" VERBATIM) add_dependencies(dep-graphs doc-xml find-installed-headers) - # These targets are the same as above, but they don't rerun the - # dependencies each time, making it faster and more convenient for - # testing. + # These targets are the same as above, but they don't rerun Doxygen + # each time, making it faster and more convenient for testing. add_custom_target(doc-check-fast COMMAND ${doc_check_command} COMMENT "Checking Doxygen documentation" VERBATIM) add_custom_target(dep-graphs-fast COMMAND ${dep_graphs_command_python} COMMAND ${dep_graphs_command_dot} COMMENT "Generating include dependency graphs" VERBATIM) + # Finding the installed headers doesn't actually run again if nothing + # has changed, so that can be safely added as a dependency. + add_dependencies(doc-check-fast find-installed-headers) + add_dependencies(dep-graphs-fast find-installed-headers) endif() endif() diff --git a/docs/doxygen/Doxyfile-common.cmakein b/docs/doxygen/Doxyfile-common.cmakein index 20a03e069f..c6555f16ea 100644 --- a/docs/doxygen/Doxyfile-common.cmakein +++ b/docs/doxygen/Doxyfile-common.cmakein @@ -27,6 +27,7 @@ INCLUDE_PATH = @CMAKE_SOURCE_DIR@/src HAVE_DOT = @DOXYGEN_DOT_FOUND@ DOT_PATH = @DOXYGEN_DOT_PATH@ MSCGEN_PATH = @DOXYGEN_MSCGEN_PATH@ +@DOXYGEN_EXTRA_SETTINGS@ ENABLED_SECTIONS = @DOXYGEN_SECTIONS@ diff --git a/docs/doxygen/Doxyfile-user.cmakein b/docs/doxygen/Doxyfile-user.cmakein index c3ad8ad9a8..9d2c67377d 100644 --- a/docs/doxygen/Doxyfile-user.cmakein +++ b/docs/doxygen/Doxyfile-user.cmakein @@ -2,10 +2,7 @@ # These pages include documentation that does not belong to the public API # documentation; exclude them from the generated documentation -EXCLUDE += @CMAKE_SOURCE_DIR@/docs/doxygen/doxygen.md -EXCLUDE += @CMAKE_SOURCE_DIR@/docs/doxygen/unittesting.md -EXCLUDE += @CMAKE_SOURCE_DIR@/docs/doxygen/wrapperbinary.md -EXCLUDE += @CMAKE_SOURCE_DIR@/docs/doxygen/simd.md +EXCLUDE += @CMAKE_CURRENT_SOURCE_DIR@/lib INTERNAL_DOCS = NO HIDE_UNDOC_CLASSES = YES diff --git a/docs/doxygen/directories.cpp b/docs/doxygen/directories.cpp index c7bd01ab35..a98c001e3c 100644 --- a/docs/doxygen/directories.cpp +++ b/docs/doxygen/directories.cpp @@ -6,9 +6,12 @@ Doxygen documentation file for directories in the source tree. \author Teemu Murtola */ -/*! -\libinternal -\dir doxygen +/*! \libinternal +\dir docs +\brief Build system and source code for various documentation items. + */ +/*! \libinternal +\dir docs/doxygen \brief Doxygen build system and general documentation content. */ @@ -149,7 +152,6 @@ Doxygen documentation file for directories in the source tree. \ingroup module_testutils */ - /*! \libinternal \dir src/testutils/tests @@ -166,17 +168,3 @@ Doxygen documentation file for directories in the source tree. \dir share/template \brief Template code for writing analysis programs. */ - -/*! -\file share/template/template.cpp -\brief Template code for writing analysis programs. - -See \ref page_analysistemplate for more information. - */ - -/*! -\example template.cpp -\brief Template code for writing analysis programs. - -See \ref page_analysistemplate for more information. - */ diff --git a/docs/doxygen/doxygen.md b/docs/doxygen/lib/doxygen.md similarity index 99% rename from docs/doxygen/doxygen.md rename to docs/doxygen/lib/doxygen.md index 2373591a73..f9583280ff 100644 --- a/docs/doxygen/doxygen.md +++ b/docs/doxygen/lib/doxygen.md @@ -461,10 +461,11 @@ placed in the page hierarchy by making it a subpage of another page, i.e., it should be referenced once using \c \\subpage. `mainpage.md` is the root of the hierarchy. -If you need to exclude a page from the public API docs, you need to add it to -an exclude list in `Doxyfile-user.cmakein`, and ensure that there are no -references to the page from public API documentation. \c \\if `libapi` can be -used to add references in content that is otherwise public. +There are two subdirectories, `user/` and `lib/`, determining the highest +documentation level where the page appears. If you add pages to `lib/`, ensure +that there are no references to the page from public API documentation. +\c \\if `libapi` can be used to add references in content that is otherwise +public. Generally, the pages should be on a high enough level and provide overview content that is useful enough such that it is not necessary to exclude them from the library API documentation. diff --git a/docs/doxygen/simd.md b/docs/doxygen/lib/simd.md similarity index 100% rename from docs/doxygen/simd.md rename to docs/doxygen/lib/simd.md diff --git a/docs/doxygen/unittesting.md b/docs/doxygen/lib/unittesting.md similarity index 100% rename from docs/doxygen/unittesting.md rename to docs/doxygen/lib/unittesting.md diff --git a/docs/doxygen/wrapperbinary.md b/docs/doxygen/lib/wrapperbinary.md similarity index 100% rename from docs/doxygen/wrapperbinary.md rename to docs/doxygen/lib/wrapperbinary.md diff --git a/docs/doxygen/misc.cpp b/docs/doxygen/misc.cpp index 895a34924f..69f9b9e12e 100644 --- a/docs/doxygen/misc.cpp +++ b/docs/doxygen/misc.cpp @@ -36,7 +36,7 @@ A separate page describes the responsibilities of these modules: \ref page_analysisframework */ -/*! +/*! \libinternal \defgroup group_mdrun Modules for simulation functionality \brief Modules used in running simulations with mdrun @@ -59,3 +59,17 @@ This namespace is used to contain some implementation-specific functions and classes. These are not meant for direct user access, but typically reside in public headers because of implementation reasons. */ + +/*! +\file share/template/template.cpp +\brief Template code for writing analysis programs. + +See \ref page_analysistemplate for more information. + */ + +/*! +\example template.cpp +\brief Template code for writing analysis programs. + +See \ref page_analysistemplate for more information. + */ diff --git a/docs/doxygen/analysisdata.md b/docs/doxygen/user/analysisdata.md similarity index 100% rename from docs/doxygen/analysisdata.md rename to docs/doxygen/user/analysisdata.md diff --git a/docs/doxygen/analysisframework.md b/docs/doxygen/user/analysisframework.md similarity index 100% rename from docs/doxygen/analysisframework.md rename to docs/doxygen/user/analysisframework.md diff --git a/docs/doxygen/analysistemplate.md b/docs/doxygen/user/analysistemplate.md similarity index 100% rename from docs/doxygen/analysistemplate.md rename to docs/doxygen/user/analysistemplate.md diff --git a/docs/doxygen/codelayout.md b/docs/doxygen/user/codelayout.md similarity index 100% rename from docs/doxygen/codelayout.md rename to docs/doxygen/user/codelayout.md diff --git a/docs/doxygen/mainpage.md b/docs/doxygen/user/mainpage.md similarity index 100% rename from docs/doxygen/mainpage.md rename to docs/doxygen/user/mainpage.md diff --git a/docs/doxygen/selections.md b/docs/doxygen/user/selections.md similarity index 100% rename from docs/doxygen/selections.md rename to docs/doxygen/user/selections.md diff --git a/docs/doxygen/usinglibrary.md b/docs/doxygen/user/usinglibrary.md similarity index 100% rename from docs/doxygen/usinglibrary.md rename to docs/doxygen/user/usinglibrary.md -- 2.22.0