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

diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt
index 30dbf7cc204a74c6e72db58ec6cab6c66b132c39..7ffe276de5d3c69fb49ddb90cab59b33bc824e81 100644 (file)
--- 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 20a03e069fd4594b10202233c2c42d45b8eaad15..c6555f16ea82c40c3613a540e0fa51caf78c88a8 100644 (file)
--- 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 c3ad8ad9a85c6148d84f4af87d2a84128328b681..9d2c67377dbfa9613f00b673ac18922cc0ee545e 100644 (file)
--- 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 c7bd01ab359d85347b799473abe79849377a5cd9..a98c001e3c1403911d98029131e40ddf33a7c0bf 100644 (file)
--- 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 <teemu.murtola@gmail.com>
 */
 
-/*!
-\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 2373591a730037dcb81ac939aa0e193de3148e78..f9583280ffa956b5bcab51656d9161cdac4fac0f 100644 (file)
--- 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 895a34924ff97565060aeb3e0c8ba9f1b5fdfc1c..69f9b9e12ea3caf53eb04ccf62bd8d001de9a5ca 100644 (file)
--- 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