From: Mark Abraham Date: Thu, 10 Jul 2014 12:52:15 +0000 (+0200) Subject: Generalize markdown configuration machinery X-Git-Url: http://biod.pnpi.spb.ru/gitweb/?a=commitdiff_plain;h=93356df4624bc4345a52814cd432f1874e89530d;p=alexxy%2Fgromacs.git Generalize markdown configuration machinery This implementation scales a bit better as we increase the number of markdown files. It may even be easier to understand! Preserves existing top-level targets, and general behaviour. The full ARGN functionality is not yet used, but it will be shortly. Introduced stub user guide, with HTML and PDF build. Change-Id: I198f273a08f81035694c3efefd35a5b2f2af7f0d --- diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 454758697f..dd043ecd78 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -38,14 +38,111 @@ # pages), and content generated from the gmx program for the various # tools (man and HTML pages). It also provides the "webpage" target, # that combines all of the above (except man pages in man format) into -# a form suitable for automated deployment to the GROMACS website. +# a form suitable for automated deployment to the GROMACS website. It +# also provides the INSTALL file for the tarball. +# +# All of the markdown content is configured, and we'd like to do that +# at build time rather than configure time (for speed, when not +# building markdown content). Also, the way they should be configured +# varies with whether the source is a tarball or repo, and which file +# is being configured. So several *_IS_POSSIBLE variables are used to +# direct the configure-time logic so that all appropriate variables +# are set by the time the configure-markdown.cmake.in file is +# configured, so that later it can do the configuration of all the +# markdown files and the right thing will happen in each case. # Even if we aren't going to make the full webpage, set up to put all # the documentation output in the same place, for convenience set(HTML_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/html") file(MAKE_DIRECTORY ${HTML_OUTPUT_DIR}) +if(${CMAKE_CURRENT_BINARY_DIR} STREQUAL ${CMAKE_CURRENT_SOURCE_DIR}) + set(MARKDOWN_CONFIGURE_IS_POSSIBLE off) +else() + set(MARKDOWN_CONFIGURE_IS_POSSIBLE on) +endif() +find_package(Pandoc) + +# Set up common infrastructure for configuring markdown at build time. +# Do replacement of CMake variables for version strings, etc. The use +# of configure-markdown.cmake defers until build time the +# configuration of markdown files, which could be faster for all the +# configurations that don't make the documentation even though it was +# possible, and helps avoid global re-configures if these files +# change. +set(SCRIPT_TO_CONFIGURE_MARKDOWN ${CMAKE_CURRENT_BINARY_DIR}/configure-markdown.cmake) +configure_file(configure-markdown.cmake.in + ${SCRIPT_TO_CONFIGURE_MARKDOWN} + @ONLY) + +# Makes a custom command to configure a Markdown file found in the +# current source directory with the configure-markdown.make script +# produced above. The result is placed in the current binary directory +# for future use. +function(configure_markdown MARKDOWN_FILE) + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${MARKDOWN_FILE} + COMMAND ${CMAKE_COMMAND} + -D FILE_TO_CONFIGURE=${CMAKE_CURRENT_SOURCE_DIR}/${MARKDOWN_FILE} + -D CONFIGURED_FILE=${CMAKE_CURRENT_BINARY_DIR}/${MARKDOWN_FILE} + -P ${SCRIPT_TO_CONFIGURE_MARKDOWN} + DEPENDS + ${SCRIPT_TO_CONFIGURE_MARKDOWN} + ${CMAKE_CURRENT_SOURCE_DIR}/${MARKDOWN_FILE} + COMMENT "Configuring Markdown" + VERBATIM + ) +endfunction() + +# Makes a custom command to make single-page HTML from Markdown. Takes +# a NAME argument for an output filename prefix, and a list of full +# paths to input files to concatenate with Pandoc into the HTML +# output. +function(make_markdown_html NAME) + add_custom_command( + OUTPUT ${HTML_OUTPUT_DIR}/${NAME}.html + COMMAND + ${PANDOC_EXECUTABLE} ${ARGN} -o ${HTML_OUTPUT_DIR}/${NAME}.html -s --toc --css buttondown.css + DEPENDS ${ARGN} + VERBATIM + ) +endfunction() + +# Makes a custom command to make PDF from Markdown. Takes a NAME +# argument for an output filename prefix, and a list of full paths to +# input files to concatenate with Pandoc into the PDF. +function(make_markdown_pdf NAME) + add_custom_command( + OUTPUT ${HTML_OUTPUT_DIR}/${NAME}.pdf + COMMAND + ${PANDOC_EXECUTABLE} ${ARGN} -o ${HTML_OUTPUT_DIR}/${NAME}.pdf -s --toc + DEPENDS ${ARGN} + VERBATIM + ) +endfunction() + +# function(make_markdown_multipage_html NAME) +# # Make the multi-page HTML install guide +# +# # TODO This is currently disabled, because the pandoc-specific +# # buttondown.css doesn't work with the different kind of output +# # makeinfo produces. When we understand better how we want to do +# # generation, decide whether we want multi-page HTML output and +# # how to make it work well. +# +# add_custom_command( +# OUTPUT ${HTML_OUTPUT_DIR}/${HTML_DIR}/index.html +# COMMAND +# ${PANDOC_EXECUTABLE} ${ARGN} -o ${NAME}.texi -s +# COMMAND +# ${MAKEINFO_EXECUTABLE} ${NAME}.texi --html -o ${HTML_OUTPUT_DIR}/${NAME} --css-ref buttondown.css +# DEPENDS ${ARGN} +# VERBATIM +# ) +# endfunction() + add_subdirectory(install-guide) +add_subdirectory(user-guide) add_subdirectory(man) add_subdirectory(old-html) add_subdirectory(doxygen) @@ -61,8 +158,6 @@ if(GMX_BUILD_MANUAL) add_subdirectory(manual) endif() -find_package(Pandoc) - 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 @@ -71,7 +166,7 @@ set(HTML_BUILD_IS_POSSIBLE OFF) if(GMX_BUILD_WEBPAGE AND GMX_BUILD_HELP AND NOT ${CMAKE_BINARY_DIR} STREQUAL ${CMAKE_SOURCE_DIR} AND - INSTALL_GUIDE_BUILD_IS_POSSIBLE AND + MARKDOWN_CONFIGURE_IS_POSSIBLE AND MANUAL_BUILD_IS_POSSIBLE AND PANDOC_EXECUTABLE AND DOXYGEN_EXECUTABLE AND @@ -86,8 +181,9 @@ if(HTML_BUILD_IS_POSSIBLE) # tarball. Then, the *_MD5SUM and *_TARBALL variables will be able # to be set on the cmake command line (e.g. by a Jenkins job # configuration), and we can require that they are set. For local - # building of the webpages (e.g. for debugging), the *_MD5SUM - # variables need a fallback. + # building of the webpages (e.g. for debugging), those variables + # can be left unset, and if so, the download section will not be + # constructed. if(NOT SOURCE_IS_SOURCE_DISTRIBUTION) if (SOURCE_TARBALL AND SOURCE_MD5SUM AND REGRESSIONTESTS_TARBALL AND REGRESSIONTESTS_MD5SUM) @@ -104,9 +200,9 @@ if(HTML_BUILD_IS_POSSIBLE) set(BUILD_DOWNLOAD_SECTION on) endif() - # If building from the repo, then tarballs may not exist, and if - # so, it would not make sense to build that part of the front - # page. + # If building the webpage from the repo, then tarballs may not + # exist, and if so, it would not make sense to build that part of + # the front page from index.md. if(BUILD_DOWNLOAD_SECTION) set(DOWNLOAD_SECTION "# Downloads @@ -138,24 +234,6 @@ if(HTML_BUILD_IS_POSSIBLE) set(DOWNLOAD_SECTION "") endif() - # Do replacement of CMake variables for version strings, etc. - configure_file(configure-html.cmake.in - ${CMAKE_CURRENT_BINARY_DIR}/configure-html.cmake - @ONLY) - - # This defers until build time the configuration of - # index.md, which could be faster - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/index.md - COMMAND ${CMAKE_COMMAND} - -P ${CMAKE_CURRENT_BINARY_DIR}/configure-html.cmake - DEPENDS - ${CMAKE_CURRENT_BINARY_DIR}/configure-html.cmake - ${CMAKE_CURRENT_SOURCE_DIR}/index.md - COMMENT "Configuring index.md" - VERBATIM - ) - # Put the CSS in the HTML output directory add_custom_command( OUTPUT ${HTML_OUTPUT_DIR}/buttondown.css @@ -165,14 +243,6 @@ if(HTML_BUILD_IS_POSSIBLE) ) list(APPEND extra_webpage_dependencies ${HTML_OUTPUT_DIR}/buttondown.css) - # Make the top-level index.html - add_custom_command( - OUTPUT ${HTML_OUTPUT_DIR}/index.html - COMMAND ${PANDOC_EXECUTABLE} -o ${HTML_OUTPUT_DIR}/index.html index.md -s --css buttondown.css - DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/index.md ${HTML_OUTPUT_DIR}/buttondown.css - VERBATIM - ) - # Make the PDF reference guide # TODO Try to make the PDF arrive directly in ${HTML_OUTPUT_DIR} add_custom_command( @@ -218,13 +288,15 @@ if(HTML_BUILD_IS_POSSIBLE) ) endif() + configure_markdown(index.md) + make_markdown_html(index ${CMAKE_CURRENT_BINARY_DIR}/index.md) + # Add a top-level target for the others to hook onto add_custom_target(webpage DEPENDS ${HTML_OUTPUT_DIR}/index.html install-guide - ${HTML_OUTPUT_DIR}/install-guide.html - ${HTML_OUTPUT_DIR}/install-guide.pdf + user-guide ${HTML_OUTPUT_DIR}/manual-${PROJECT_VERSION}.pdf ${extra_webpage_dependencies} VERBATIM diff --git a/docs/configure-html.cmake.in b/docs/configure-html.cmake.in deleted file mode 100644 index 07a2626af7..0000000000 --- a/docs/configure-html.cmake.in +++ /dev/null @@ -1,12 +0,0 @@ -# Helper script that defers configure_file until build time, so that -# changes to the files configured for the html files don't trigger a -# global reconfigure - -set(SRC_DIR "@CMAKE_CURRENT_SOURCE_DIR@") -set(BIN_DIR "@CMAKE_CURRENT_BINARY_DIR@") - -set(PROJECT_VERSION "@PROJECT_VERSION@") -set(DOWNLOAD_SECTION "@DOWNLOAD_SECTION@") - -configure_file(${SRC_DIR}/index.md - ${BIN_DIR}/index.md @ONLY) diff --git a/docs/configure-markdown.cmake.in b/docs/configure-markdown.cmake.in new file mode 100644 index 0000000000..0f99002bea --- /dev/null +++ b/docs/configure-markdown.cmake.in @@ -0,0 +1,15 @@ +# Helper script that defers configure_file of markdown until build +# time, so that changes to the files configured here don't trigger a +# global reconfigure + +# Now configure the values for all the variables that might later +# configure any of the markdown files. +set(PROJECT_VERSION "@PROJECT_VERSION@") +set(GMX_CMAKE_MINIMUM_REQUIRED_VERSION "@GMX_CMAKE_MINIMUM_REQUIRED_VERSION@") +set(REQUIRED_CUDA_VERSION "@REQUIRED_CUDA_VERSION@") +set(REQUIRED_CUDA_COMPUTE_CAPABILITY "@REQUIRED_CUDA_COMPUTE_CAPABILITY@") +set(REGRESSIONTEST_VERSION "@REGRESSIONTEST_VERSION@") +set(DOWNLOAD_SECTION "@DOWNLOAD_SECTION@") + +configure_file(${FILE_TO_CONFIGURE} + ${CONFIGURED_FILE} @ONLY) diff --git a/docs/index.md b/docs/index.md index 4bdc1180f1..3202891fe6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,8 @@ * [Installation Guide](install-guide.html) As [PDF](install-guide.pdf) -* User Guide - coming soon! +* [User Guide](user-guide.html) + As [PDF](user-guide.pdf) * [Online Reference](online.html) diff --git a/docs/install-guide/CMakeLists.txt b/docs/install-guide/CMakeLists.txt index 770240d29a..7342ba4d71 100644 --- a/docs/install-guide/CMakeLists.txt +++ b/docs/install-guide/CMakeLists.txt @@ -32,36 +32,13 @@ # To help us fund GROMACS development, we humbly ask that you cite # the research papers on the package. Check out http://www.gromacs.org. -set(INSTALL_GUIDE_BUILD_IS_POSSIBLE OFF) -if(NOT ${CMAKE_BINARY_DIR} STREQUAL ${CMAKE_SOURCE_DIR}) - # We can only build the install guide outside of the source dir - find_package(Pandoc) - if(PANDOC_EXECUTABLE) - set(INSTALL_GUIDE_BUILD_IS_POSSIBLE ON) - endif() -endif() - -if(INSTALL_GUIDE_BUILD_IS_POSSIBLE) - # Do replacement of CMake variables for version strings, etc. - # This defers until build time the configuration of - # install-guide.md, which could be faster for all the - # configurations that don't make the install guide even though it - # was possible. - configure_file(configure-install-guide.cmake.in - ${CMAKE_CURRENT_BINARY_DIR}/configure-install-guide.cmake - @ONLY) - - # Configure the install-guide.md at build time - add_custom_command( - OUTPUT ${CMAKE_BINARY_DIR}/install-guide.md - COMMAND ${CMAKE_COMMAND} - -P ${CMAKE_CURRENT_BINARY_DIR}/configure-install-guide.cmake - DEPENDS - ${CMAKE_CURRENT_BINARY_DIR}/configure-install-guide.cmake - ${CMAKE_CURRENT_SOURCE_DIR}/install-guide.md - COMMENT "Configuring install guide" - VERBATIM - ) +# Note that the install-guide target, etc. can still be built +# independent of the webpage target. +if(MARKDOWN_CONFIGURE_IS_POSSIBLE AND PANDOC_EXECUTABLE) + set(name "install-guide") + configure_markdown(${name}.md) + make_markdown_html(${name} ${CMAKE_CURRENT_BINARY_DIR}/${name}.md) + make_markdown_pdf(${name} ${CMAKE_CURRENT_BINARY_DIR}/${name}.md) # Make the INSTALL file for CPack for the tarball. This gets put # into the tarball via the CPack rules in the top-level @@ -69,59 +46,18 @@ if(INSTALL_GUIDE_BUILD_IS_POSSIBLE) add_custom_command( OUTPUT final/INSTALL COMMAND ${CMAKE_COMMAND} -E make_directory final - COMMAND ${PANDOC_EXECUTABLE} -t plain -o final/INSTALL install-guide.md + COMMAND ${PANDOC_EXECUTABLE} -t plain -o final/INSTALL ${name}.md DEPENDS - ${CMAKE_BINARY_DIR}/install-guide.md + ${CMAKE_CURRENT_BINARY_DIR}/${name}.md VERBATIM ) - # Make the single-page HTML install guide - add_custom_command( - OUTPUT ${HTML_OUTPUT_DIR}/install-guide.html - COMMAND - ${PANDOC_EXECUTABLE} install-guide.md -o ${HTML_OUTPUT_DIR}/install-guide.html -s --toc --css buttondown.css - DEPENDS - ${CMAKE_BINARY_DIR}/install-guide.md - VERBATIM - ) - - # Make the PDF install guide - add_custom_command( - OUTPUT ${HTML_OUTPUT_DIR}/install-guide.pdf - COMMAND - ${PANDOC_EXECUTABLE} install-guide.md -o ${HTML_OUTPUT_DIR}/install-guide.pdf -s --toc - DEPENDS - ${CMAKE_BINARY_DIR}/install-guide.md - VERBATIM - ) - - # Make the multi-page HTML install guide - # - # TODO This is currently disabled, because the pandoc-specific - # buttondown.css doesn't work with the different kind of output - # makeinfo produces. When we understand better how we want to - # do generation, decide whether we want multi-page HTML output - # and how to make it work well. - # - # add_custom_command( - # OUTPUT ${HTML_OUTPUT_DIR}/index.html - # COMMAND - # ${PANDOC_EXECUTABLE} install-guide.md -o install-guide.texi -s - # COMMAND - # ${MAKEINFO_EXECUTABLE} install-guide.texi --html -o ${HTML_OUTPUT_DIR}/install-guide --css-ref buttondown.css - # DEPENDS - # ${CMAKE_BINARY_DIR}/install-guide.md - # VERBATIM - # ) - # Add a top-level target for the webpage build to hook onto - add_custom_target(install-guide + add_custom_target(${name} DEPENDS final/INSTALL - ${HTML_OUTPUT_DIR}/install-guide.html - ${HTML_OUTPUT_DIR}/install-guide.pdf + ${HTML_OUTPUT_DIR}/${name}.html + ${HTML_OUTPUT_DIR}/${name}.pdf VERBATIM ) endif() - -set(INSTALL_GUIDE_BUILD_IS_POSSIBLE ${INSTALL_GUIDE_BUILD_IS_POSSIBLE} PARENT_SCOPE) diff --git a/docs/install-guide/configure-install-guide.cmake.in b/docs/install-guide/configure-install-guide.cmake.in deleted file mode 100644 index 8980df6bab..0000000000 --- a/docs/install-guide/configure-install-guide.cmake.in +++ /dev/null @@ -1,15 +0,0 @@ -# Helper script that defers configure_file until build time, so -# that changes to the files configured here don't trigger -# a global reconfigure - -set(SRC_DIR "@CMAKE_CURRENT_SOURCE_DIR@") -set(BIN_DIR "@CMAKE_CURRENT_BINARY_DIR@") - -set(PROJECT_VERSION "@PROJECT_VERSION@") -set(GMX_CMAKE_MINIMUM_REQUIRED_VERSION "@GMX_CMAKE_MINIMUM_REQUIRED_VERSION@") -set(REQUIRED_CUDA_VERSION "@REQUIRED_CUDA_VERSION@") -set(REQUIRED_CUDA_COMPUTE_CAPABILITY "@REQUIRED_CUDA_COMPUTE_CAPABILITY@") -set(REGRESSIONTEST_VERSION "@REGRESSIONTEST_VERSION@") - -configure_file(${SRC_DIR}/install-guide.md - ${BIN_DIR}/install-guide.md @ONLY) diff --git a/docs/user-guide/CMakeLists.txt b/docs/user-guide/CMakeLists.txt new file mode 100644 index 0000000000..28477eb168 --- /dev/null +++ b/docs/user-guide/CMakeLists.txt @@ -0,0 +1,50 @@ +# +# This file is part of the GROMACS molecular simulation package. +# +# Copyright (c) 2014, 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. +# +# GROMACS is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public License +# as published by the Free Software Foundation; either version 2.1 +# of the License, or (at your option) any later version. +# +# GROMACS is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with GROMACS; if not, see +# http://www.gnu.org/licenses, or write to the Free Software Foundation, +# Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +# +# If you want to redistribute modifications to GROMACS, please +# consider that scientific software is very special. Version +# control is crucial - bugs must be traceable. We will be happy to +# consider code for inclusion in the official distribution, but +# derived work must not be called official GROMACS. Details are found +# in the README & COPYING files - if they are missing, get the +# official version at http://www.gromacs.org. +# +# To help us fund GROMACS development, we humbly ask that you cite +# the research papers on the package. Check out http://www.gromacs.org. + +# Note that the user-guide target, etc. can still be built +# independent of the webpage target. +if(MARKDOWN_CONFIGURE_IS_POSSIBLE AND PANDOC_EXECUTABLE) + set(name "user-guide") + configure_markdown(main.md) + make_markdown_html(${name} ${CMAKE_CURRENT_BINARY_DIR}/main.md) + make_markdown_pdf(${name} ${CMAKE_CURRENT_BINARY_DIR}/main.md) + + # Add a top-level target for the webpage build to hook onto + add_custom_target(${name} + DEPENDS + ${HTML_OUTPUT_DIR}/${name}.html + ${HTML_OUTPUT_DIR}/${name}.pdf + VERBATIM + ) +endif() diff --git a/docs/user-guide/main.md b/docs/user-guide/main.md new file mode 100644 index 0000000000..ab05a9f7d1 --- /dev/null +++ b/docs/user-guide/main.md @@ -0,0 +1,5 @@ +% User guide for GROMACS @PROJECT_VERSION@ + +# Introduction # + +Coming soon!