Misc. improvements to docs build system

- Get rid of GMX_BUILD_WEBPAGE.  It did not disable any user-visible
  detection, but only affected what build rules were generated, and none
  of those affected the default 'all' target.  Now the webpage target is
  always created, and any informative messages that were previously
  given during CMake time with GMX_BUILD_WEBPAGE=ON are now given when
  the user tries to build the target.
- For all the documentation custom targets, create a dummy target that
  gives a message to the user when building if the tools required to
  build that target are not available.
- Reduce the required dependencies for the 'webpage' target.  If some
  non-essential parts cannot be built, just give a message to the user
  and build the remaining parts with some broken links.

These should make the build system easier to document and to understand
from the user's perspective.

Change-Id: Ib65e3348b88b1e0461f1f69ba1218f09d376a6dc

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index b9ef0a280f9c7876357544674b68efea91007efe..1a4f40eacf95cb8348f6f9c93e64d355ce99cf96 100644 (file)
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -51,9 +51,10 @@
 # conf-vars.py.cmakein), which in turn is included by the Sphinx configuration
 # file conf.py.
 
-option(GMX_BUILD_WEBPAGE "Whether to try to configure to build the GROMACS static webpages" OFF)
-option(GMX_BUILD_MANUAL "Whether to try to configure to build the PDF manual" OFF)
-mark_as_advanced(GMX_BUILD_WEBPAGE GMX_BUILD_MANUAL)
+set(SOURCE_MD5SUM "unknown" CACHE STRING
+    "MD5 sum of the source tarball, normally used only for the pre-release webpage build")
+# REGRESSIONTEST_MD5SUM is set in cmake/gmxVersionInfo.cmake because it is used also in tests/CMakeLists.txt
+mark_as_advanced(SOURCE_MD5SUM)
 
 set(EXPECTED_DOXYGEN_VERSION 1.8.5)
 
@@ -75,16 +76,7 @@ if (SOURCE_IS_SOURCE_DISTRIBUTION)
 endif()
 
 add_subdirectory(doxygen)
-
-set(SOURCE_MD5SUM "unknown" CACHE STRING "MD5 sum of the source tarball, normally used only for the pre-release webpage build")
-# REGRESSIONTEST_MD5SUM is set in cmake/gmxVersionInfo.cmake because it is used also in tests/CMakeLists.txt
-mark_as_advanced(SOURCE_MD5SUM)
-
-if(GMX_BUILD_MANUAL)
-    # Make sure we only do detection of manual-building dependencies
-    # when the user opted in for that.
-    add_subdirectory(manual)
-endif()
+add_subdirectory(manual)
 
 if (SPHINX_FOUND)
     # We need to have all the Sphinx input files in a single directory, and
@@ -176,6 +168,8 @@ if (SPHINX_FOUND)
     gmx_add_custom_output_target(sphinx-input OUTPUT STAMP
         DEPENDS ${SPHINX_INPUT_FILES})
     # TODO: Make this remove obsolete .rst files.
+    # TODO: This does not work in cross-compilation scenarios; disable up to
+    # the necessary level.
     gmx_add_custom_output_target(sphinx-programs OUTPUT STAMP
         COMMAND ${CMAKE_COMMAND} -E make_directory onlinehelp
         COMMAND gmx -quiet help -export rst
@@ -249,6 +243,15 @@ if (SPHINX_FOUND)
         # manually build the target.
         set(MAN_PAGE_DIR ${CMAKE_CURRENT_BINARY_DIR})
     endif()
+else()
+    add_custom_target(webpage-sphinx
+        COMMAND ${CMAKE_COMMAND} -E echo
+            "HTML pages cannot be built because Sphinx is not available"
+        VERBATIM)
+    add_custom_target(man
+        COMMAND ${CMAKE_COMMAND} -E echo
+            "man pages cannot be built because Sphinx is not available"
+        VERBATIM)
 endif()
 
 if (MAN_PAGE_DIR)
@@ -266,68 +269,81 @@ if (MAN_PAGE_DIR)
 endif()
 gmx_cpack_add_generated_source_directory(man)
 
-set(HTML_BUILD_IS_POSSIBLE OFF)
-# We can only configure to build the webpage if the user asked for it,
-# the build is outside of the source dir, and all the components can
-# be built. There's no intrinsic need to be talkative if we fail -
-# most people never need to know, unless they've asked for the webpage
-# build.
-if(GMX_BUILD_WEBPAGE)
-    set(HTML_BUILD_IS_POSSIBLE ON)
-    # Next, turn it off in any of the preconditions are unsatisified
-
-    if(NOT MANUAL_BUILD_IS_POSSIBLE)
-        set(HTML_BUILD_IS_POSSIBLE OFF)
-        message(STATUS "Cannot build webpage without being able to build the reference PDF manual")
-    endif()
-
-    if(NOT PYTHON_EXECUTABLE)
-        set(HTML_BUILD_IS_POSSIBLE OFF)
-        message(STATUS "Cannot build webpage without python")
-    endif()
+# Determine whether we can build all the HTML pages and content linked from
+# there.  If not, construct an informative message if the user tries to
+# build the target; most people never need to know, unless they've asked for
+# the webpage build.
+set(HTML_BUILD_IS_POSSIBLE ON)
+set(HTML_BUILD_NOT_POSSIBLE_REASON)
+set(HTML_BUILD_WARNINGS)
 
-    if(NOT SPHINX_FOUND)
-        set(HTML_BUILD_IS_POSSIBLE OFF)
-        message(STATUS "Cannot build webpage without sphinx")
-    endif()
+# Next, turn it off if any of the preconditions are unsatisified
+if (NOT PYTHON_EXECUTABLE)
+    set(HTML_BUILD_IS_POSSIBLE OFF)
+    set(HTML_BUILD_NOT_POSSIBLE_REASON "Python is required")
+elseif (NOT SPHINX_FOUND)
+    # Hardly anything gets built if Sphinx is not available, so don't bother.
+    set(HTML_BUILD_IS_POSSIBLE OFF)
+    set(HTML_BUILD_NOT_POSSIBLE_REASON "Sphinx is required")
+endif()
+if (NOT MANUAL_BUILD_IS_POSSIBLE)
+    list(APPEND HTML_BUILD_WARNINGS
+         "Reference PDF manual was not built, so links to it do not work")
+endif()
+if (NOT DOXYGEN_EXECUTABLE)
+    list(APPEND HTML_BUILD_WARNINGS
+        "Doxygen was not available, so links to Doxygen do not work")
+endif()
+if (NOT DOXYGEN_DOT_EXECUTABLE)
+    list(APPEND HTML_BUILD_WARNINGS
+        "dot/graphviz was not found, so some graphs are missing")
+endif()
 
-    if(NOT DOXYGEN_EXECUTABLE)
-        set(HTML_BUILD_IS_POSSIBLE OFF)
-        message(STATUS "Cannot build webpage without doxygen")
+if (HTML_BUILD_IS_POSSIBLE)
+    set(_webpage_target_properties)
+    if (HTML_BUILD_WARNINGS)
+        list(APPEND _webpage_target_properties
+             COMMAND ${CMAKE_COMMAND} -E echo
+                 "webpage was built, but with the following limitations:")
+        foreach(_warning ${HTML_BUILD_WARNINGS})
+        list(APPEND _webpage_target_properties
+             COMMAND ${CMAKE_COMMAND} -E echo " - ${_warning}")
+        endforeach()
     endif()
 
-    if(NOT DOXYGEN_MSCGEN_EXECUTABLE)
-        set(HTML_BUILD_IS_POSSIBLE OFF)
-        message(STATUS "Cannot build webpage without mscgen")
+    if (MANUAL_BUILD_IS_POSSIBLE)
+        # Make the PDF reference guide
+        # TODO Try to make the PDF arrive directly in ${HTML_OUTPUT_DIR}
+        # TODO Make this depend on the output of the manual build, so that the
+        # file actually gets copied multiple times.
+        set(_manual_target_location ${HTML_OUTPUT_DIR}/manual-${GMX_VERSION_STRING}.pdf)
+        add_custom_command(
+            OUTPUT ${_manual_target_location}
+            COMMAND ${CMAKE_COMMAND}
+                -E remove -f ${_manual_target_location}
+            COMMAND ${CMAKE_COMMAND}
+                -E copy ${CMAKE_CURRENT_BINARY_DIR}/manual/gromacs.pdf ${_manual_target_location}
+            DEPENDS manual
+            VERBATIM)
+        list(APPEND _webpage_target_properties
+             DEPENDS ${_manual_target_location})
     endif()
-endif()
-
-if(HTML_BUILD_IS_POSSIBLE)
-    # Make the PDF reference guide
-    # TODO Try to make the PDF arrive directly in ${HTML_OUTPUT_DIR}
-    add_custom_command(
-        OUTPUT ${HTML_OUTPUT_DIR}/manual-${GMX_VERSION_STRING}.pdf
-        COMMAND ${CMAKE_COMMAND}
-            -E remove -f ${HTML_OUTPUT_DIR}/manual-${GMX_VERSION_STRING}.pdf
-        COMMAND ${CMAKE_COMMAND}
-            -E copy ${CMAKE_CURRENT_BINARY_DIR}/manual/gromacs.pdf ${HTML_OUTPUT_DIR}/manual-${GMX_VERSION_STRING}.pdf
-        # UseLATEX.cmake makes a target called pdf, not ${CMAKE_CURRENT_BINARY_DIR}/manual/gromacs.pdf
-        DEPENDS pdf
-        VERBATIM
-        )
 
     # The Doxygen configuration in doxygen/Doxyfile-common.cmakein
     # makes all the Doxygen output directly in
     # ${HTML_OUTPUT_DIR}/doxygen (and makes the directory if it needs
     # to).
 
-    # Add a top-level target for the others to hook onto
-    add_custom_target(webpage
-        DEPENDS ${HTML_OUTPUT_DIR}/manual-${GMX_VERSION_STRING}.pdf)
+    # Add a top-level target that builds everything related to the webpage,
+    # for Jenkins (and possibly others) to use
+    add_custom_target(webpage ${_webpage_target_properties}
+        COMMENT "Building webpage"
+        VERBATIM)
     add_dependencies(webpage webpage-sphinx doxygen-all)
 else()
     add_custom_target(webpage
-        COMMAND ${CMAKE_COMMAND} -E echo "Cannot build webpage because of missing requirements. Check cmake status output for reasons"
-        COMMENT "Webpage build disabled"
-        )
+        COMMAND ${CMAKE_COMMAND} -E echo
+            "Cannot build webpage because ${HTML_BUILD_NOT_POSSIBLE_REASON}"
+        COMMENT "Webpage build not possible"
+        VERBATIM)
 endif()

diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst
index 855202aaff247be93be8135cac0fd4e9646b9e19..43bce33b84a9aec291064db0cdf34f401bade8e9 100644 (file)
--- a/docs/dev-manual/tools.rst
+++ b/docs/dev-manual/tools.rst
@@ -162,8 +162,6 @@ You need to enable at least some of the following CMake options:
   Option that controls 1) whether shell completions are built automatically,
   and 2) whether built man pages are installed if available (the user still needs
   to build the ``man`` target manually before installing)
-``GMX_BUILD_WEBPAGE``
-  Option needed for compiling all the documentation into the webpage
 
 Some documentation cannot be built if the CMake option
 ``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it

diff --git a/docs/doxygen/CMakeLists.txt b/docs/doxygen/CMakeLists.txt
index c42eb5ac0df83c7a9c5393a4087e8049933da238..ff9dc058a8fb518d34dcf7912c8a2721f501c315 100644 (file)
--- a/docs/doxygen/CMakeLists.txt
+++ b/docs/doxygen/CMakeLists.txt
@@ -1,7 +1,7 @@
 #
 # This file is part of the GROMACS molecular simulation package.
 #
-# Copyright (c) 2012,2013,2014, by the GROMACS development team, led by
+# Copyright (c) 2012,2013,2014,2015, by the GROMACS development team, led by
 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
 # and including many others, as listed in the AUTHORS file in the
 # top-level source directory and at http://www.gromacs.org.
@@ -214,9 +214,28 @@ if (DOXYGEN_FOUND)
             --ignore ${CMAKE_CURRENT_SOURCE_DIR}/suppressions.txt
             --ignore-cycles ${CMAKE_CURRENT_SOURCE_DIR}/cycle-suppressions.txt)
         add_custom_target(check-source      COMMAND ${check_source_command}
-            COMMENT "Checking Doxygen documentation" VERBATIM)
+            COMMENT "Checking source code for various issues" VERBATIM)
         add_custom_target(check-source-fast COMMAND ${check_source_command}
-            COMMENT "Checking Doxygen documentation" VERBATIM)
+            COMMENT "Checking source code for various issues" VERBATIM)
         add_dependencies(check-source       doxygen-xml)
     endif()
+else()
+    function (add_disabled_doxygen_target TARGET)
+        add_custom_target(${TARGET}
+            COMMAND ${CMAKE_COMMAND} -E echo
+                "Cannot build/run target ${TARGET} because Doxygen is not available"
+            COMMENT "Doxygen not available" VERBATIM)
+    endfunction()
+    add_disabled_doxygen_target(doxygen-all)
+    add_disabled_doxygen_target(doxygen-all-fast)
+    add_disabled_doxygen_target(doxygen-xml)
+    add_disabled_doxygen_target(doxygen-user)
+    add_disabled_doxygen_target(doxygen-lib)
+    add_disabled_doxygen_target(doxygen-lib-fast)
+    add_disabled_doxygen_target(doxygen-full)
+    add_disabled_doxygen_target(doxygen-full-fast)
+    add_disabled_doxygen_target(check-source)
+    add_disabled_doxygen_target(check-source-fast)
+    add_disabled_doxygen_target(dep-graphs)
+    add_disabled_doxygen_target(dep-graphs-fast)
 endif()

diff --git a/docs/manual/CMakeLists.txt b/docs/manual/CMakeLists.txt
index 459043138241fc498fa47f83d515ab3eac575830..6c4b466cf1dc3634e67b4ec11d55a820be5af2d4 100644 (file)
--- a/docs/manual/CMakeLists.txt
+++ b/docs/manual/CMakeLists.txt
@@ -32,23 +32,32 @@
 # To help us fund GROMACS development, we humbly ask that you cite
 # the research papers on the package. Check out http://www.gromacs.org.
 
-if (BUILD_IS_INSOURCE)
+# TODO: Consider whether this could just be replaced by using
+# GMX_DEVELOPER_BUILD to control this as well.
+option(GMX_BUILD_MANUAL "Whether to try to configure to build the PDF manual" OFF)
+mark_as_advanced(GMX_BUILD_MANUAL)
+
+set(MANUAL_BUILD_IS_POSSIBLE ON)
+set(MANUAL_BUILD_NOT_POSSIBLE_REASON)
+if (NOT GMX_BUILD_MANUAL)
+    # Make sure we only do detection of manual-building dependencies
+    # when the user opted in for that.
+    set(MANUAL_BUILD_IS_POSSIBLE OFF)
+    set(MANUAL_BUILD_NOT_POSSIBLE_REASON "GMX_BUILD_MANUAL is not ON")
+elseif (BUILD_IS_INSOURCE)
     # UseLATEX.cmake does not work with an in-source build
-    message(STATUS "Cannot build the manual when building in the source directory")
     set(MANUAL_BUILD_IS_POSSIBLE OFF)
+    set(MANUAL_BUILD_NOT_POSSIBLE_REASON "the build is in-source")
 else()
-    INCLUDE(UseLATEX.cmake)
+    include(UseLATEX.cmake)
 
     if(NOT PDFLATEX_COMPILER OR NOT IMAGEMAGICK_CONVERT)
-        # No pdflatex was found, so don't build the manual.
-        message(STATUS "A required dependency of the manual (pdflatex, ImageMagick's convert) was not found, so the manual build will not be available")
         set(MANUAL_BUILD_IS_POSSIBLE OFF)
+        set(MANUAL_BUILD_NOT_POSSIBLE_REASON "pdflatex or some other dependency (ImageMagick convert) is not available")
 
         # TODO Later, identify other dependencies like bibtex,
         # make_index, date, some graphics conversion program,
         # etc. Perhaps patch UseLATEX.cmake and contribute upstream.
-    else()
-        set(MANUAL_BUILD_IS_POSSIBLE ON)
     endif()
 endif()
 
@@ -95,8 +104,10 @@ if(MANUAL_BUILD_IS_POSSIBLE)
     # to be built.
     add_custom_target(manual DEPENDS pdf)
 else()
-    # TODO Arrange for the "make manual" target to explain that this can't
-    # be done
+    add_custom_target(manual
+        COMMAND ${CMAKE_COMMAND} -E echo
+        "Cannot build PDF manual, because ${MANUAL_BUILD_NOT_POSSIBLE_REASON}"
+        VERBATIM)
 endif()
 
 set(MANUAL_BUILD_IS_POSSIBLE ${MANUAL_BUILD_IS_POSSIBLE} PARENT_SCOPE)