# 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)
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
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
# 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)
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
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
)
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(
)
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
+++ /dev/null
-# 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)
--- /dev/null
+# 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)
* [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)
# 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
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)
+++ /dev/null
-# 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)
--- /dev/null
+#
+# 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()
--- /dev/null
+% User guide for GROMACS @PROJECT_VERSION@
+
+# Introduction #
+
+Coming soon!