set(EXPECTED_DOXYGEN_VERSION 1.8.5)
-set(EXPECTED_SPHINX_VERSION 1.4.1)
+set(EXPECTED_SPHINX_VERSION 1.6.1)
if (DEFINED PYTHON_EXECUTABLE)
# Keep quiet on subsequent runs of cmake
set(HTML_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
file(MAKE_DIRECTORY ${HTML_OUTPUT_DIR})
+# Prepare directories for pdf/tex output
+set(TEX_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/manual")
+set(SPHINX_LATEX_FILE "${TEX_OUTPUT_DIR}/gromacs.tex")
+file(MAKE_DIRECTORY ${TEX_OUTPUT_DIR})
+
# The directory from which man pages will be installed; if it remains
# empty, they will be silently skipped.
set(MAN_PAGE_DIR)
endif()
add_subdirectory(doxygen)
-add_subdirectory(manual)
-
if (SPHINX_FOUND)
# We need to have all the Sphinx input files in a single directory, and
# since some of them are generated, we copy everything into the build tree,
# to this directory.
set(SPHINX_INPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx-input)
set(SPHINX_EXTENSION_PATH ${CMAKE_CURRENT_SOURCE_DIR})
+ # As the manual build now depends also on Sphinx, the inclusion path needs
+ # to be set after we know the basic information for Sphinx.
+ add_subdirectory(manual)
if (SOURCE_MD5SUM STREQUAL "unknown")
# But for testing the webpage build (e.g. from the repo) we
# need a default value.
# this should be set to the matching MD5 sum.
set(REGRESSIONTEST_MD5SUM_STRING "${REGRESSIONTEST_MD5SUM}")
endif()
+ # The reference manual still contains the individual sections from the
+ # LaTeX document, with the files below grouped and annotated by chapter.
+ set(REFERENCEMANUAL_SPHINX_FILES_GENERAL
+ # Main index file, preface and introduction.
+ reference-manual/index.rst
+ reference-manual/preface.rst
+ reference-manual/introduction.rst
+ # Definitions and Units chapter
+ reference-manual/definitions.rst
+ # Topologies chapter
+ reference-manual/topologies.rst
+ reference-manual/topologies/particle-type.rst
+ reference-manual/topologies/parameter-files.rst
+ reference-manual/topologies/molecule-definition.rst
+ reference-manual/topologies/constraint-algorithm-section.rst
+ reference-manual/topologies/pdb2gmx-input-files.rst
+ reference-manual/topologies/topology-file-formats.rst
+ reference-manual/topologies/force-field-organization.rst
+ # File formats chapter
+ reference-manual/file-formats.rst
+ # Run parameters and programs chapter
+ reference-manual/run-parameters.rst
+ # Implementation details chapter
+ reference-manual/details.rst
+ # Averages and fluctations chapter
+ reference-manual/averages.rst
+ # References
+ reference-manual/references.rst
+ # PNG formated plot files that don't need to be converted into PNG
+ # for the web page.
+ reference-manual/plots/peregrine.png
+ reference-manual/plots/adress.png
+ reference-manual/plots/plotje.png
+ reference-manual/plots/xvgr.png
+ )
+ set(REFERENCEMANUAL_SPHINX_FILES_WITH_IMAGES
+ # Algorithms chapter
+ reference-manual/algorithms.rst
+ reference-manual/algorithms/periodic-boundary-conditions.rst
+ reference-manual/algorithms/group-concept.rst
+ reference-manual/algorithms/molecular-dynamics.rst
+ reference-manual/algorithms/shell-molecular-dynamics.rst
+ reference-manual/algorithms/constraint-algorithms.rst
+ reference-manual/algorithms/simulated-annealing.rst
+ reference-manual/algorithms/stochastic-dynamics.rst
+ reference-manual/algorithms/brownian-dynamics.rst
+ reference-manual/algorithms/energy-minimization.rst
+ reference-manual/algorithms/normal-mode-analysis.rst
+ reference-manual/algorithms/free-energy-calculations.rst
+ reference-manual/algorithms/replica-exchange.rst
+ reference-manual/algorithms/essential-dynamics.rst
+ reference-manual/algorithms/expanded-ensemble.rst
+ reference-manual/algorithms/parallelization-domain-decomp.rst
+ # Interaction functions and force fields chapter
+ reference-manual/functions.rst
+ reference-manual/functions/bonded-interactions.rst
+ reference-manual/functions/force-field.rst
+ reference-manual/functions/free-energy-interactions.rst
+ reference-manual/functions/interaction-methods.rst
+ reference-manual/functions/long-range-electrostatics.rst
+ reference-manual/functions/long-range-vdw.rst
+ reference-manual/functions/nonbonded-interactions.rst
+ reference-manual/functions/polarization.rst
+ reference-manual/functions/restraints.rst
+ # Special topics chapter
+ reference-manual/special.rst
+ reference-manual/special/free-energy-implementation.rst
+ reference-manual/special/pulling.rst
+ reference-manual/special/awh.rst
+ reference-manual/special/enforced-rotation.rst
+ reference-manual/special/electric-fields.rst
+ reference-manual/special/comp-electrophys.rst
+ reference-manual/special/free-energy-pmf.rst
+ reference-manual/special/remove-fast-dgf.rst
+ reference-manual/special/viscosity-calculation.rst
+ reference-manual/special/tabulated-interaction-functions.rst
+ reference-manual/special/qmmm.rst
+ reference-manual/special/vmd-imd.rst
+ reference-manual/special/membrane-embedding.rst
+ # Analysis chapter
+ reference-manual/analysis.rst
+ reference-manual/analysis/using-groups.rst
+ reference-manual/analysis/looking-at-trajectory.rst
+ reference-manual/analysis/general-properties.rst
+ reference-manual/analysis/radial-distribution-function.rst
+ reference-manual/analysis/correlation-function.rst
+ reference-manual/analysis/curve-fitting.rst
+ reference-manual/analysis/mean-square-displacement.rst
+ reference-manual/analysis/bond-angle-dihedral.rst
+ reference-manual/analysis/radius-of-gyration.rst
+ reference-manual/analysis/rmsd.rst
+ reference-manual/analysis/covariance-analysis.rst
+ reference-manual/analysis/dihedral-pca.rst
+ reference-manual/analysis/protein-related.rst
+ reference-manual/analysis/interface-related.rst)
+ # The image files have also been ordered by the respective
+ # chapter they are included in in the reference manual
+ set(REFERENCEMANUAL_IMAGE_FILES
+ # General folder
+ reference-manual/plots/decomp.pdf
+ reference-manual/plots/dih.pdf
+ reference-manual/plots/drift-all.pdf
+ reference-manual/plots/f-angle.pdf
+ reference-manual/plots/f-bond.pdf
+ reference-manual/plots/fp-highres.pdf
+ reference-manual/plots/int-mat.pdf
+ reference-manual/plots/mdpar.pdf
+ reference-manual/plots/parsort.pdf
+ reference-manual/plots/ring.pdf
+ reference-manual/plots/shiftf.pdf
+ # Algorithms chapter
+ reference-manual/algorithms/plots/dd-cells.pdf
+ reference-manual/algorithms/plots/dd-tric.pdf
+ reference-manual/algorithms/plots/flowchart.pdf
+ reference-manual/algorithms/plots/free1.pdf
+ reference-manual/algorithms/plots/free2.pdf
+ reference-manual/algorithms/plots/leapfrog.pdf
+ reference-manual/algorithms/plots/lincs.pdf
+ reference-manual/algorithms/plots/maxwell.pdf
+ reference-manual/algorithms/plots/mpmd-pme.pdf
+ reference-manual/algorithms/plots/nstric.pdf
+ reference-manual/algorithms/plots/par-lincs2.pdf
+ reference-manual/algorithms/plots/pbctric.pdf
+ reference-manual/algorithms/plots/rhododec.pdf
+ reference-manual/algorithms/plots/truncoct.pdf
+ reference-manual/algorithms/plots/verlet-drift.pdf
+ # Interaction functions chapter
+ reference-manual/functions/plots/angle.pdf
+ reference-manual/functions/plots/bstretch.pdf
+ reference-manual/functions/plots/chain.pdf
+ reference-manual/functions/plots/dummies.pdf
+ reference-manual/functions/plots/f-bham.pdf
+ reference-manual/functions/plots/fbposres.pdf
+ reference-manual/functions/plots/f-dih.pdf
+ reference-manual/functions/plots/f-dr.pdf
+ reference-manual/functions/plots/fig-02.pdf
+ reference-manual/functions/plots/fig-04.pdf
+ reference-manual/functions/plots/f-imps.pdf
+ reference-manual/functions/plots/f-lj.pdf
+ reference-manual/functions/plots/f-morse.pdf
+ reference-manual/functions/plots/f-pr.pdf
+ reference-manual/functions/plots/f-rbs.pdf
+ reference-manual/functions/plots/ring-imp.pdf
+ reference-manual/functions/plots/softcore.pdf
+ reference-manual/functions/plots/subst-im.pdf
+ reference-manual/functions/plots/tetra-im.pdf
+ reference-manual/functions/plots/vcrf.pdf
+ reference-manual/functions/plots/vsite-4fdn.pdf
+ # Special topics chapter
+ reference-manual/special/plots/awh-invN.pdf
+ reference-manual/special/plots/awh-pmfs.pdf
+ reference-manual/special/plots/awh-sampleweights.pdf
+ reference-manual/special/plots/awh-traj.pdf
+ reference-manual/special/plots/compelsetup.pdf
+ reference-manual/special/plots/dumaro.pdf
+ reference-manual/special/plots/dumtypes.pdf
+ reference-manual/special/plots/equipotential.pdf
+ reference-manual/special/plots/field.pdf
+ reference-manual/special/plots/gaussians.pdf
+ reference-manual/special/plots/pulldirrel.pdf
+ reference-manual/special/plots/pull.pdf
+ reference-manual/special/plots/pullref.pdf
+ reference-manual/special/plots/rotation.pdf
+ # Analysis chapter
+ reference-manual/analysis/plots/dih-def.pdf
+ reference-manual/analysis/plots/distm.pdf
+ reference-manual/analysis/plots/dssp.pdf
+ reference-manual/analysis/plots/hbond-insert.pdf
+ reference-manual/analysis/plots/hbond.pdf
+ reference-manual/analysis/plots/hpr-wheel.pdf
+ reference-manual/analysis/plots/msdwater.pdf
+ reference-manual/analysis/plots/ngmxdump.pdf
+ reference-manual/analysis/plots/phipsi.pdf
+ reference-manual/analysis/plots/rama.pdf
+ reference-manual/analysis/plots/rdfO-O.pdf
+ reference-manual/analysis/plots/rdf.pdf
+ reference-manual/analysis/plots/sgangle.pdf
+ )
set(SPHINX_SOURCE_FILES
index.rst
download.rst
- dev-manual/index.rst
+ conf.py
+ links.dat
dev-manual/build-system.rst
+ dev-manual/change-management.rst
dev-manual/commitstyle.rst
dev-manual/documentation-generation.rst
+ dev-manual/contribute.rst
dev-manual/doxygen.rst
dev-manual/error-handling.rst
dev-manual/formatting.rst
dev-manual/gmxtree.rst
dev-manual/includestyle.rst
+ dev-manual/index.rst
dev-manual/jenkins.rst
dev-manual/language-features.rst
dev-manual/naming.rst
dev-manual/overview.rst
+ dev-manual/physical_validation.rst
dev-manual/redmine-states.png
dev-manual/relocatable-binaries.rst
dev-manual/reportstyle.rst
dev-manual/tools.rst
dev-manual/uncrustify.rst
fragments/doxygen-links.rst
+ how-to/index.rst
+ how-to/beginners.rst
+ how-to/topology.rst
+ how-to/special.rst
+ how-to/visualize.rst
install-guide/index.rst
release-notes/index.rst
+ release-notes/2019/major/highlights.rst
+ release-notes/2019/major/features.rst
+ release-notes/2019/major/performance.rst
+ release-notes/2019/major/tools.rst
+ release-notes/2019/major/bugs-fixed.rst
+ release-notes/2019/major/removed-functionality.rst
+ release-notes/2019/major/deprecated-functionality.rst
+ release-notes/2019/major/portability.rst
+ release-notes/2019/major/miscellaneous.rst
release-notes/2018/2018.4.rst
release-notes/2018/2018.3.rst
release-notes/2018/2018.2.rst
release-notes/2016/major/removed-features.rst
release-notes/2016/major/miscellaneous.rst
release-notes/older/index.rst
- user-guide/index.rst
+ # the entry for user-guide/index.rst should not appear here,
+ # as it will be included conditionally further down depending on
+ # if the documentation will be build with the full reference
+ # manual or without.
+ user-guide/cmdline.rst
user-guide/cutoff-schemes.rst
- user-guide/getting-started.rst
- user-guide/force-fields.rst
+ user-guide/deprecation-policy.rst
+ user-guide/environment-variables.rst
user-guide/faq.rst
- user-guide/flow.rst
user-guide/floating-point.rst
- user-guide/system-preparation.rst
+ user-guide/flow.rst
+ user-guide/force-fields.rst
+ user-guide/getting-started.rst
+ user-guide/index.rst
user-guide/managing-simulations.rst
+ user-guide/mdp-options.rst
user-guide/mdrun-features.rst
user-guide/mdrun-performance.rst
- user-guide/mdp-options.rst
user-guide/run-time-errors.rst
- user-guide/file-formats.rst
- user-guide/cmdline.rst
- user-guide/environment-variables.rst
user-guide/security.rst
+ user-guide/system-preparation.rst
user-guide/terminology.rst
- user-guide/plotje.gif
- user-guide/xvgr.gif
- conf.py
- links.dat
)
include(SphinxMacros.cmake)
gmx_init_sphinx_setup(${SPHINX_INPUT_DIR})
+ # set temporary variables for doi inclusion
+ # into the manual, plain string + some wrapping
+ # for release builds, and dummy string for non-release
+ # builds
+ if("${GMX_MANUAL_DOI}" STREQUAL "")
+ # empty string means no doi, set dummy text
+ set(GMX_MANUAL_DOI_STRING "This is not a release build of GROMACS, so please reference")
+ set(GMX_MANUAL_DOI_STRING "${GMX_MANUAL_DOI_STRING} one of the GROMACS papers and the base release of the manual.")
+ else()
+ # release version, set plain old boring string
+ set(GMX_MANUAL_DOI_STRING "Please reference this documentation as https://doi.org/${GMX_MANUAL_DOI}.")
+ endif()
+ # same for source doi, but modify the text
+ if("${GMX_SOURCE_DOI}" STREQUAL "")
+ # empty string means no release build
+ set(GMX_SOURCE_DOI_STRING "This is not a release build of GROMACS. Please reference one of the")
+ set(GMX_SOURCE_DOI_STRING "${GMX_SOURCE_DOI_STRING} GROMACS papers, as well as the base release that this version is built from.")
+ set(GMX_SOURCE_DOI_STRING "${GMX_SOURCE_DOI_STRING} Also, please state what modifcations have been performed or where the version")
+ set(GMX_SOURCE_DOI_STRING "${GMX_SOURCE_DOI_STRING} was sourced from.")
+ else()
+ # release version, give them a doi url string
+ set(GMX_SOURCE_DOI_STRING "To cite the source code for this release, please cite")
+ set(GMX_SOURCE_DOI_STRING "${GMX_SOURCE_DOI_STRING} https://doi.org/${GMX_SOURCE_DOI}.")
+ endif()
+
+ if(IMAGE_CONVERT_POSSIBLE)
+ set(IMAGE_CONVERT_STRING "possible")
+ else()
+ set(IMAGE_CONVERT_STRING "impossible")
+ endif()
+
set(SPHINX_CONFIG_VARS_FILE ${SPHINX_INPUT_DIR}/conf-vars.py)
gmx_configure_version_file(conf-vars.py.cmakein ${SPHINX_CONFIG_VARS_FILE}
EXTRA_VARS
SPHINX_EXTENSION_PATH RELENG_PATH
+ IMAGE_CONVERT_STRING
EXPECTED_DOXYGEN_VERSION
EXPECTED_SPHINX_VERSION
CMAKE_MINIMUM_REQUIRED_VERSION REQUIRED_CUDA_VERSION
REQUIRED_CUDA_COMPUTE_CAPABILITY REGRESSIONTEST_VERSION
SOURCE_MD5SUM REGRESSIONTEST_MD5SUM_STRING
GMX_TNG_MINIMUM_REQUIRED_VERSION
- GMX_LMFIT_MINIMUM_REQUIRED_VERSION
+ GMX_LMFIT_REQUIRED_VERSION
+ GMX_MANUAL_DOI_STRING
+ GMX_SOURCE_DOI_STRING
COMMENT "Configuring Sphinx configuration file")
gmx_add_sphinx_input_file(${SPHINX_CONFIG_VARS_FILE})
gmx_add_sphinx_source_files(FILES ${SPHINX_SOURCE_FILES})
dev-manual/releng/jenkins-ui.rst
)
endif()
- gmx_add_sphinx_input_target(sphinx-input)
+ gmx_add_sphinx_source_files(
+ FILES
+ ${REFERENCEMANUAL_SPHINX_FILES_GENERAL})
+ if (IMAGE_CONVERT_POSSIBLE)
+ gmx_add_sphinx_source_files(
+ FILES
+ ${REFERENCEMANUAL_SPHINX_FILES_WITH_IMAGES}
+ ${REFERENCEMANUAL_IMAGE_FILES})
+ gmx_add_sphinx_image_conversion_files(
+ FILES
+ ${REFERENCEMANUAL_IMAGE_FILES})
+ endif()
+ gmx_add_sphinx_input_target(sphinx-input-rst)
+ gmx_add_sphinx_image_conversion_target(sphinx-image-conversion)
+ add_custom_target(sphinx-input)
+ add_dependencies(sphinx-input sphinx-input-rst sphinx-image-conversion)
# Remove other rst files from the build tree, since they confuse Sphinx.
# Skip generated files in onlinehelp/, and fragments.
# The latter do not cause issues with obsolete files, as they
add_custom_target(install-guide
COMMAND
${SPHINX_EXECUTABLE}
- -q -b text
+ -q -E -b text
-w sphinx-install.log
-d ${CMAKE_CURRENT_BINARY_DIR}/install-guide/_doctrees
-c ${SPHINX_INPUT_DIR}
# Sphinx cache with pickled ReST documents
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
-
add_custom_target(webpage-sphinx
+ DEPENDS sphinx-programs
+ DEPENDS sphinx-input
+ DEPENDS sphinx-image-conversion
COMMAND
${CMAKE_COMMAND} -E make_directory ${SPHINX_INPUT_DIR}/_static
COMMAND
${SPHINX_EXECUTABLE}
- -q -b html
+ -q -E -b html
-w sphinx-html.log
-d "${SPHINX_CACHE_DIR}"
"${SPHINX_INPUT_DIR}"
COMMENT "Building HTML documentation with Sphinx"
VERBATIM
)
- add_dependencies(webpage-sphinx sphinx-input sphinx-programs)
add_custom_target(man
COMMAND
${SPHINX_EXECUTABLE}
- -q -b man
+ -q -E -b man
-w sphinx-man.log
-d ${SPHINX_CACHE_DIR}
-t do_man
# manually build the target.
set(MAN_PAGE_DIR ${CMAKE_CURRENT_BINARY_DIR})
endif()
+
else()
+ set(MANUAL_BUILD_IS_POSSIBLE OFF)
+ set(MANUAL_BUILD_NOT_POSSIBLE_REASON "Sphinx version ${EXPECTED_SPHINX_VERSION} is not available")
+
add_custom_target(webpage-sphinx
COMMAND ${CMAKE_COMMAND} -E echo
"HTML pages cannot be built because Sphinx version ${EXPECTED_SPHINX_VERSION} is not available"
COMMAND ${CMAKE_COMMAND} -E echo
"man pages cannot be built because Sphinx version ${EXPECTED_SPHINX_VERSION} is not available"
VERBATIM)
+ add_custom_target(sphinx-create-texman
+ COMMAND ${CMAKE_COMMAND} -E echo
+ "Cannot prepare LaTeX input files because Sphinx version ${EXPECTED_SPHINX_VERSION} is not available"
+ VERBATIM)
endif()
if (MAN_PAGE_DIR)