From: Teemu Murtola Date: Wed, 13 May 2015 18:11:03 +0000 (+0300) Subject: Misc. improvements to docs build system X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=f077ffa9c9cd6b2e25235372d77063ac70b24b62;p=alexxy%2Fgromacs.git 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 b9ef0a280f..1a4f40eacf 100644 --- 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 855202aaff..43bce33b84 100644 --- 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 c42eb5ac0d..ff9dc058a8 100644 --- 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 4590431382..6c4b466cf1 100644 --- 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)