From 389918c50f268127b3d0497b27715987dc2caea4 Mon Sep 17 00:00:00 2001 From: Teemu Murtola Date: Sun, 1 Feb 2015 07:25:41 +0200 Subject: [PATCH] Replace tool HTML help with Sphinx-generated docs Instead of generating HTML pages directly, make 'gmx help -export rst' export reStructuredText that is used as input for Sphinx to generate the help pages as part of the Sphinx documentation. Make other docs refer to these with a native Sphinx construct :ref:`gmx something`, as it seems not possible to make `gmx something`_ really work. :doc:`/programs/gmx-something` works even nicer, but is a bit too much typing. Make various minor corrections to existing help documentation so that they can be converted to rst without errors; the output is still very ugly in several places (but it wasn't any better in the old HTML...). This change does not aim to fix all problems; it will probably be easier once we have more freedom in using different rst constructs. Links to file formats do not work, but those should be easier to fix once the file format descriptions are also in rst. Remove installation of the old share/html/ pages, as there is very little stuff left there. Change-Id: Ie9d7f1435656d9cf1f60a7e1c4c3c2e440af227d --- docs/CMakeLists.txt | 11 +- docs/conf.py | 23 --- docs/install-guide/index.rst | 28 ++-- docs/old-html/CMakeLists.txt | 11 +- docs/user-guide/getting-started.rst | 28 ++-- docs/user-guide/tools.rst | 18 ++- src/gromacs/commandline/cmdlinehelpmodule.cpp | 147 ++++++++++-------- src/gromacs/commandline/cmdlinehelpwriter.cpp | 35 ++--- src/gromacs/gmxana/gmx_chi.c | 2 +- src/gromacs/gmxana/gmx_current.c | 2 +- src/gromacs/gmxana/gmx_hbond.c | 18 +-- src/gromacs/gmxana/gmx_rmsdist.c | 2 +- src/gromacs/gmxana/gmx_trjcat.c | 6 +- src/gromacs/gmxana/gmx_tune_pme.c | 4 +- src/gromacs/gmxana/gmx_wham.cpp | 4 +- src/gromacs/gmxpreprocess/grompp.c | 11 +- src/gromacs/onlinehelp/helpwritercontext.cpp | 82 +++++----- src/gromacs/onlinehelp/helpwritercontext.h | 4 +- .../trajectoryanalysis/modules/freevolume.cpp | 5 +- src/programs/mdrun/mdrun.cpp | 2 +- 20 files changed, 211 insertions(+), 232 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 28fac6bae3..cedb7907c9 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -113,6 +113,15 @@ if (SPHINX_FOUND) endforeach() gmx_add_custom_output_target(sphinx-input OUTPUT STAMP DEPENDS ${SPHINX_INPUT_FILES}) + gmx_add_custom_output_target(sphinx-programs OUTPUT STAMP + COMMAND ${CMAKE_COMMAND} -E make_directory programs + COMMAND gmx -quiet help -export rst + DEPENDS gmx + WORKING_DIRECTORY ${SPHINX_INPUT_DIR} + COMMENT "Generating reStructuredText help") + # This dependency ensures that the directories exist before the + # executable tries to write things there. + add_dependencies(sphinx-programs sphinx-input) # Make the INSTALL file for CPack for the tarball. This gets put # into the tarball via the CPack rules below, which requires that @@ -182,7 +191,7 @@ if (SPHINX_FOUND) COMMENT "Building HTML documentation with Sphinx" VERBATIM ) - add_dependencies(webpage-sphinx sphinx-input) + add_dependencies(webpage-sphinx sphinx-input sphinx-programs) endif() set(HTML_BUILD_IS_POSSIBLE OFF) diff --git a/docs/conf.py b/docs/conf.py index 8b878590fa..067ce0d426 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -168,29 +168,6 @@ rst_epilog += """ .. _sample mdp file: ../online/mdp.html .. _download: ../download.html -.. TODO Consider generating these (e.g. with the commandline module that also generates the link targets). For now, - the Jenkins link checker will keep things working. - -.. _gmx bar: ../programs/gmx-bar.html -.. _gmx energy: ../programs/gmx-energy.html -.. _gmx convert-tpr: ../programs/gmx-convert-tpr.html -.. _gmx dipoles: ../programs/gmx-dipoles.html -.. _gmx tune_pme: ../programs/gmx-tune_pme.html -.. _gmx do_dssp: ../programs/gmx-do_dssp.html -.. _gmx view: ../programs/gmx-view.html -.. _gmx eneconv: ../programs/gmx-eneconv.html -.. _gmx wham: ../programs/gmx-wham.html -.. _gmx grompp: ../programs/gmx-grompp.html -.. _gmx solvate: ../programs/gmx-solvate.html -.. _gmx editconf: ../programs/gmx-editconf.html -.. _gmx pdb2gmx: ../programs/gmx-pdb2gmx.html -.. _gmx trjconv: ../programs/gmx-trjconv.html -.. _gmx trjcat: ../programs/gmx-trjcat.html -.. _gmx eneconv: ../programs/gmx-eneconv.html -.. _gmx mdrun: ../programs/gmx-mdrun.html -.. _mdrun: ../programs/gmx-mdrun.html -.. _mdrun_mpi: ../programs/gmx-mdrun.html - .. _pdb: ../online/pdb.html .. _gro: ../online/gro.html .. _top: ../online/top.html diff --git a/docs/install-guide/index.rst b/docs/install-guide/index.rst index 8be0d5a71b..9d50b111e7 100644 --- a/docs/install-guide/index.rst +++ b/docs/install-guide/index.rst @@ -54,7 +54,7 @@ appropriate value instead of ``xxx`` : * ``-DCMAKE_CXX_COMPILER=xxx`` equal to the name of the C++98 `compiler`_ you wish to use (or the environment variable ``CXX``) * ``-DGMX_MPI=on`` to build using `MPI support`_ * ``-DGMX_GPU=on`` to build using nvcc to run with an NVIDIA `native GPU acceleration`_ -* ``-DGMX_SIMD=xxx`` to specify the level of `SIMD support`_ of the node on which mdrun_ will run +* ``-DGMX_SIMD=xxx`` to specify the level of `SIMD support`_ of the node on which :ref:`gmx mdrun` will run * ``-DGMX_BUILD_MDRUN_ONLY=on`` for `building only mdrun`_, e.g. for compute cluster back-end nodes * ``-DGMX_DOUBLE=on`` to run |Gromacs| in double precision (slower, and not normally useful) * ``-DCMAKE_PREFIX_PATH=xxx`` to add a non-standard location for CMake to `search for libraries, headers or programs`_ @@ -193,7 +193,7 @@ different options and parallelization schemes for the actual simulations you want to run. You will still get *good*, performance with the default build and runtime options, but if you truly want to push your hardware to the performance limit, the days of -just blindly starting programs with mdrun_ are gone. +just blindly starting programs with :ref:`gmx mdrun` are gone. CMake ----- @@ -285,7 +285,7 @@ Optional build components matrix manipulation, but they do not provide any benefits for normal simulations. Configuring these are discussed at `linear algebra libraries`_. -* The built-in |Gromacs| trajectory viewer `gmx view`_ requires X11 and +* The built-in |Gromacs| trajectory viewer :ref:`gmx view` requires X11 and Motif/Lesstif libraries and header files. You may prefer to use third-party software for visualization, such as VMD_ or PyMol_. * An external TNG library for trajectory-file handling can be used, @@ -466,15 +466,15 @@ highest number in the list is generally the one you should choose: 8. ``Sparc64_HPC_ACE`` Fujitsu machines like the K computer have this. The CMake configure system will check that the compiler you have -chosen can target the architecture you have chosen. mdrun_ will check +chosen can target the architecture you have chosen. :ref:`gmx mdrun` will check further at runtime, so if in doubt, choose the lowest setting you -think might work, and see what mdrun_ says. The configure system also +think might work, and see what :ref:`gmx mdrun` says. The configure system also works around many known issues in many versions of common HPC compilers. However, since the options also enable general compiler flags for the platform in question, you can end up in situations where e.g. an ``AVX_128_FMA`` binary will just crash on any Intel machine, since the code will try to execute general illegal -instructions (inserted by the compiler) before mdrun_ gets to the +instructions (inserted by the compiler) before :ref:`gmx mdrun` gets to the architecture detection routines. A further ``GMX_SIMD=Reference`` option exists, which is a special @@ -597,16 +597,16 @@ architectures does not support the ``RDTSCP`` instruction. However, we discourage attempts to use a single |Gromacs| installation when the execution environment is heterogeneous, such as a mix of AVX and earlier hardware, because this will lead to programs (especially -mdrun_) that run slowly on the new hardware. Building two full +:ref:`gmx mdrun`) that run slowly on the new hardware. Building two full installations and locally managing how to call the correct one (e.g. using the module system) is the recommended approach. Alternatively, as at the moment the |Gromacs| tools do not make strong use of SIMD acceleration, it can be convenient to create an installation with tools portable across different x86 machines, but -with separate mdrun_ binaries for each architecture. To achieve this, +with separate :ref:`gmx mdrun` binaries for each architecture. To achieve this, one can first build a full installation with the least-common-denominator SIMD instruction set, e.g. ``-DGMX_SIMD=SSE2``, -then build separate mdrun_ binaries for each architecture present in +then build separate :ref:`gmx mdrun` binaries for each architecture present in the heterogeneous environment. By using custom binary and library suffixes for the mdrun-only builds, these can be installed to the same location as the "generic" tools installation. @@ -641,7 +641,7 @@ Changing the names of |Gromacs| binaries and libraries It is sometimes convenient to have different versions of the same |Gromacs| programs installed. The most common use cases have been single and double precision, and with and without MPI. This mechanism can -also be used to install side-by-side multiple versions of mdrun_ +also be used to install side-by-side multiple versions of :ref:`gmx mdrun` optimized for different CPU architectures, as mentioned previously. By default, |Gromacs| will suffix programs and libraries for such builds @@ -725,14 +725,14 @@ Building only mdrun Past versions of the build system offered "mdrun" and "install-mdrun" targets (similarly for other programs too) to build and install only the mdrun program, respectively. Such a build is useful when the -configuration is only relevant for mdrun_ (such as with +configuration is only relevant for :ref:`gmx mdrun` (such as with parallelization options for MPI, SIMD, GPUs, or on BlueGene or Cray), or the length of time for the compile-link-install cycle is relevant when developing. This is now supported with the ``cmake`` option ``-DGMX_BUILD_MDRUN_ONLY=ON``, which will build a cut-down version of -``libgromacs`` and/or the mdrun_ program (according to whether shared +``libgromacs`` and/or the :ref:`gmx mdrun` program (according to whether shared or static). Naturally, now ``make install`` installs only those products. By default, mdrun-only builds will default to static linking against |Gromacs| libraries, because this is generally a good idea for @@ -842,7 +842,7 @@ directory: source /your/installation/prefix/here/bin/GMXRC ./gmxtest.pl all -np 2 -If your mdrun_ program has been suffixed in a non-standard way, then +If your :ref:`gmx mdrun` program has been suffixed in a non-standard way, then the ``./gmxtest.pl -mdrun`` option will let you specify that name to the test machinery. You can use ``./gmxtest.pl -double`` to test the double-precision version. You can use ``./gmxtest.pl -crosscompiling`` @@ -857,7 +857,7 @@ Testing |Gromacs| for performance We are still working on a set of benchmark systems for testing the performance of |Gromacs|. Until that is ready, we recommend that you try a few different parallelization options, and experiment with -tools such as `gmx tune_pme`_. +tools such as :ref:`gmx tune_pme`. Having difficulty? ------------------ diff --git a/docs/old-html/CMakeLists.txt b/docs/old-html/CMakeLists.txt index 2b119f9afc..facc8b0dfb 100644 --- a/docs/old-html/CMakeLists.txt +++ b/docs/old-html/CMakeLists.txt @@ -1,7 +1,7 @@ # # This file is part of the GROMACS molecular simulation package. # -# Copyright (c) 2013,2014, by the GROMACS development team, led by +# Copyright (c) 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. @@ -36,7 +36,6 @@ include(gmxCustomCommandUtilities) set(OUTPUT_DIR final) -set(HTML_PAGE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/${OUTPUT_DIR}) if (GMX_BUILD_HELP) # Unlike the man and completion targets, this target is not built # automatically with GMX_BUILD_HELP=AUTO, since most people will not @@ -67,12 +66,4 @@ if (GMX_BUILD_HELP) endif() set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES "${OUTPUT_DIR};header.html") - set(HTML_PAGE_DIR ${CMAKE_CURRENT_BINARY_DIR}/${OUTPUT_DIR}) endif() - -if (SOURCE_IS_SOURCE_DISTRIBUTION OR GMX_BUILD_HELP_FORCE) - install(DIRECTORY ${HTML_PAGE_DIR}/ - DESTINATION ${DATA_INSTALL_DIR}/html - COMPONENT html) -endif() -gmx_cpack_add_generated_source_directory(${OUTPUT_DIR}) diff --git a/docs/user-guide/getting-started.rst b/docs/user-guide/getting-started.rst index cbb055e974..b6171209b4 100644 --- a/docs/user-guide/getting-started.rst +++ b/docs/user-guide/getting-started.rst @@ -46,8 +46,8 @@ encounter. Molecular Topology file (``.top``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The molecular topology file is generated by the program `gmx -pdb2gmx`_. `gmx pdb2gmx`_ translates a PDB_ structure file of any +The molecular topology file is generated by the program :ref:`gmx pdb2gmx`. +:ref:`gmx pdb2gmx` translates a PDB_ structure file of any peptide or protein to a molecular topology file. This topology file contains a complete description of all the interactions in your peptide or protein. @@ -55,19 +55,19 @@ peptide or protein. Molecular Structure file (``.gro``, ``.pdb``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When `gmx pdb2gmx`_ is executed to generate a molecular topology, it +When :ref:`gmx pdb2gmx` is executed to generate a molecular topology, it also translates the structure file (pdb_ file) to a GROMOS structure file (gro_ file). The main difference between a pdb_ file and a gromos file is their format and that a gro_ file can also hold velocities. However, if you do not need the velocities, you can also use a PDB_ file in all programs. To generate a box of solvent -molecules around the peptide, the program `gmx solvate`_ is -used. First the program `gmx editconf`_ should be used to define a box -of appropriate size around the molecule. `gmx solvate`_ solvates a +molecules around the peptide, the program :ref:`gmx solvate` is +used. First the program :ref:`gmx editconf` should be used to define a box +of appropriate size around the molecule. :ref:`gmx solvate` solvates a solute molecule (the peptide) into any solvent (in this case, -water). The output of `gmx solvate`_ is a gromos structure file of the -peptide solvated in water. `gmx solvate`_ also changes the molecular -topology file (generated by `gmx pdb2gmx`_) to add solvent to the +water). The output of :ref:`gmx solvate` is a gromos structure file of the +peptide solvated in water. :ref:`gmx solvate` also changes the molecular +topology file (generated by :ref:`gmx pdb2gmx`) to add solvent to the topology. Molecular Dynamics parameter file (``.mdp``) @@ -94,17 +94,17 @@ The next step is to combine the molecular structure (gro_ file), topology (top_ file) MD-parameters (mdp_ file) and (optionally) the index file (ndx_) to generate a run input file (tpr_ extension). This file contains all information needed to start a simulation with -|Gromacs|. The `gmx grompp`_ program processes all input files and +|Gromacs|. The :ref:`gmx grompp` program processes all input files and generates the run input tpr_ file. Trajectory file (``.trr``, ``.tng``, or ``.xtc``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once the run input file is available, we can start the simulation. The -program which starts the simulation is called `gmx mdrun`_ (or -sometimes just mdrun, or mdrun_mpi). The only input file of `gmx -mdrun`_ that you usually need in order to start a run is the run input -file (tpr_ file). The typical output files of `gmx mdrun`_ are the +program which starts the simulation is called :ref:`gmx mdrun` (or +sometimes just mdrun, or mdrun_mpi). The only input file of :ref:`gmx mdrun` +that you usually need in order to start a run is the run input +file (tpr_ file). The typical output files of :ref:`gmx mdrun` are the trajectory file (trr_ file), a logfile (log_ file), and perhaps a checkpoint file (cpt_ file). diff --git a/docs/user-guide/tools.rst b/docs/user-guide/tools.rst index 2441f94ef1..b34b48e169 100644 --- a/docs/user-guide/tools.rst +++ b/docs/user-guide/tools.rst @@ -3,14 +3,22 @@ Command-line tools |Gromacs| includes many tools for preparing, running and analysing molecular dynamics simulations. These are all structured as part of the -gmx wrapper binary, and invoked with commands like `gmx grompp`_. mdrun_ -is the only other binary that +gmx wrapper binary, and invoked with commands like :ref:`gmx grompp`. +:ref:`mdrun ` is the only other binary that :ref:`can be built `; in the normal build it can be run with ``gmx mdrun``. Documentation for these can -be found at the links below. +be found at the links below: -- Tools documentation `by name <../programs/byname.html>`_ -- Tools documentation `by topic <../programs/bytopic.html>`_ +.. toctree:: + + /programs/byname + /programs/bytopic + +.. toctree:: + :hidden: + :glob: + + /programs/gmx-* Common options and behaviour ---------------------------- diff --git a/src/gromacs/commandline/cmdlinehelpmodule.cpp b/src/gromacs/commandline/cmdlinehelpmodule.cpp index 3a67a1ff4a..d20af6deba 100644 --- a/src/gromacs/commandline/cmdlinehelpmodule.cpp +++ b/src/gromacs/commandline/cmdlinehelpmodule.cpp @@ -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. @@ -512,16 +512,56 @@ void HelpExportMan::finishModuleGroupExport() * HelpExportHtml */ -/*! \internal \brief +/*! \internal + * \brief * Implements export for HTML help. * + * This whole class can go once docs/old-html/ no longer requires header.html + * that it generates. + * * \ingroup module_commandline */ class HelpExportHtml : public HelpExportInterface { public: //! Initializes HTML exporter. - explicit HelpExportHtml(const CommandLineHelpModuleImpl &helpModule); + HelpExportHtml(); + + virtual void startModuleExport() {} + virtual void exportModuleHelp( + const CommandLineModuleInterface & /*module*/, + const std::string & /*tag*/, + const std::string & /*displayName*/) {} + virtual void finishModuleExport() {} + + virtual void startModuleGroupExport() {} + virtual void exportModuleGroup(const char * /*title*/, + const ModuleGroupContents & /*modules*/) {} + virtual void finishModuleGroupExport() {} +}; + +HelpExportHtml::HelpExportHtml() +{ + std::string header = gmx::File::readToString("header.html.in"); + header = replaceAll(header, "@VERSION@", gmx_version()); + gmx::File::writeFileFromString("header.html", header); +} + +/******************************************************************** + * HelpExportReStructuredText + */ + +/*! \internal \brief + * Implements export for web pages as reStructuredText. + * + * \ingroup module_commandline + */ +class HelpExportReStructuredText : public HelpExportInterface +{ + public: + //! Initializes reST exporter. + explicit HelpExportReStructuredText( + const CommandLineHelpModuleImpl &helpModule); virtual void startModuleExport(); virtual void exportModuleHelp( @@ -536,20 +576,15 @@ class HelpExportHtml : public HelpExportInterface virtual void finishModuleGroupExport(); private: - void setupHeaderAndFooter(); - - void writeHtmlHeader(File *file, const std::string &title) const; - void writeHtmlFooter(File *file) const; - HelpLinks links_; boost::scoped_ptr indexFile_; - std::string header_; - std::string footer_; }; -HelpExportHtml::HelpExportHtml(const CommandLineHelpModuleImpl &helpModule) - : links_(eHelpOutputFormat_Html) +HelpExportReStructuredText::HelpExportReStructuredText( + const CommandLineHelpModuleImpl &helpModule) + : links_(eHelpOutputFormat_Rst) { +#if 0 // TODO: Investigate how these links can be made to work again. File linksFile("links.dat", "r"); std::string line; while (linksFile.readLine(&line)) @@ -557,63 +592,58 @@ HelpExportHtml::HelpExportHtml(const CommandLineHelpModuleImpl &helpModule) links_.addLink(line, "../online/" + line, line); } linksFile.close(); +#endif initProgramLinks(&links_, helpModule); - setupHeaderAndFooter(); } -void HelpExportHtml::setupHeaderAndFooter() +void HelpExportReStructuredText::startModuleExport() { - header_ = gmx::File::readToString("header.html.in"); - header_ = replaceAll(header_, "@VERSION@", gmx_version()); - gmx::File::writeFileFromString("header.html", header_); - header_ = replaceAll(header_, "@ROOTPATH@", "../"); - footer_ = gmx::File::readToString("footer.html"); + indexFile_.reset(new File("programs/byname.rst", "w")); + indexFile_->writeLine("Tools by Name"); + indexFile_->writeLine("============="); } -void HelpExportHtml::startModuleExport() -{ - indexFile_.reset(new File("final/programs/byname.html", "w")); - writeHtmlHeader(indexFile_.get(), "GROMACS Programs by Name"); - indexFile_->writeLine("

GROMACS Programs Alphabetically

"); -} - -void HelpExportHtml::exportModuleHelp( +void HelpExportReStructuredText::exportModuleHelp( const CommandLineModuleInterface &module, const std::string &tag, const std::string &displayName) { - File file("final/programs/" + tag + ".html", "w"); - writeHtmlHeader(&file, displayName); - - CommandLineHelpContext context(&file, eHelpOutputFormat_Html, &links_); + // TODO: Ideally, the file would only be touched if it really changes. + // This would make Sphinx reruns much faster. + File file("programs/" + tag + ".rst", "w"); + file.writeLine(formatString(".. _%s:", displayName.c_str())); + file.writeLine(); + file.writeLine(displayName); + file.writeLine(std::string(displayName.length(), '=')); + CommandLineHelpContext context(&file, eHelpOutputFormat_Rst, &links_); context.setModuleDisplayName(displayName); module.writeHelp(context); - - writeHtmlFooter(&file); file.close(); - indexFile_->writeLine(formatString("%s - %s
", - tag.c_str(), displayName.c_str(), + indexFile_->writeLine(formatString("* :doc:`%s <%s>` - %s", + displayName.c_str(), tag.c_str(), module.shortDescription())); } -void HelpExportHtml::finishModuleExport() +void HelpExportReStructuredText::finishModuleExport() { - writeHtmlFooter(indexFile_.get()); indexFile_->close(); + indexFile_.reset(); } -void HelpExportHtml::startModuleGroupExport() +void HelpExportReStructuredText::startModuleGroupExport() { - indexFile_.reset(new File("final/programs/bytopic.html", "w")); - writeHtmlHeader(indexFile_.get(), "GROMACS Programs by Topic"); - indexFile_->writeLine("

GROMACS Programs by Topic

"); + indexFile_.reset(new File("programs/bytopic.rst", "w")); + indexFile_->writeLine("Tools by Topic"); + indexFile_->writeLine("=============="); } -void HelpExportHtml::exportModuleGroup(const char *title, - const ModuleGroupContents &modules) +void HelpExportReStructuredText::exportModuleGroup( + const char *title, + const ModuleGroupContents &modules) { - indexFile_->writeLine(formatString("

%s

", title)); + indexFile_->writeLine(title); + indexFile_->writeLine(std::string(std::strlen(title), '-')); ModuleGroupContents::const_iterator module; for (module = modules.begin(); module != modules.end(); ++module) @@ -622,30 +652,21 @@ void HelpExportHtml::exportModuleGroup(const char *title, std::string displayName(tag); // TODO: This does not work if the binary name would contain a dash, // but that is not currently the case. - size_t dashPos = displayName.find('-'); + const size_t dashPos = displayName.find('-'); GMX_RELEASE_ASSERT(dashPos != std::string::npos, "There should always be at least one dash in the tag"); displayName[dashPos] = ' '; - indexFile_->writeLine(formatString("%s - %s
", - tag.c_str(), displayName.c_str(), + indexFile_->writeLine(formatString("| :doc:`%s <%s>` - %s", + displayName.c_str(), tag.c_str(), module->second)); } + indexFile_->writeLine(); } -void HelpExportHtml::finishModuleGroupExport() +void HelpExportReStructuredText::finishModuleGroupExport() { - writeHtmlFooter(indexFile_.get()); indexFile_->close(); -} - -void HelpExportHtml::writeHtmlHeader(File *file, const std::string &title) const -{ - file->writeLine(replaceAll(header_, "@TITLE@", title)); -} - -void HelpExportHtml::writeHtmlFooter(File *file) const -{ - file->writeLine(footer_); + indexFile_.reset(); } /******************************************************************** @@ -809,7 +830,7 @@ int CommandLineHelpModule::run(int argc, char *argv[]) // Add internal topics lazily here. addTopic(HelpTopicPointer(new CommandsHelpTopic(*impl_))); - const char *const exportFormats[] = { "man", "html", "completion" }; + const char *const exportFormats[] = { "man", "html", "rst", "completion" }; std::string exportFormat; Options options(NULL, NULL); options.addOption(StringOption("export").store(&exportFormat) @@ -824,7 +845,11 @@ int CommandLineHelpModule::run(int argc, char *argv[]) } else if (exportFormat == "html") { - exporter.reset(new HelpExportHtml(*impl_)); + exporter.reset(new HelpExportHtml()); + } + else if (exportFormat == "rst") + { + exporter.reset(new HelpExportReStructuredText(*impl_)); } else if (exportFormat == "completion") { diff --git a/src/gromacs/commandline/cmdlinehelpwriter.cpp b/src/gromacs/commandline/cmdlinehelpwriter.cpp index 0c79bd3934..50d60ce533 100644 --- a/src/gromacs/commandline/cmdlinehelpwriter.cpp +++ b/src/gromacs/commandline/cmdlinehelpwriter.cpp @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2010,2011,2012,2013,2014, by the GROMACS development team, led by + * Copyright (c) 2010,2011,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. @@ -412,9 +412,12 @@ void SynopsisFormatter::start(const char *name) lineLength_ = 70; file.writeString(name); break; - case eHelpOutputFormat_Html: - lineLength_ = 78; - file.writeLine("
");
+        case eHelpOutputFormat_Rst:
+            lineLength_ = 74;
+            indent_    += 4;
+            file.writeLine("::");
+            file.writeLine();
+            file.writeString("    ");
             file.writeString(name);
             break;
         default:
@@ -426,10 +429,6 @@ void SynopsisFormatter::finish()
 {
     File &file = context_.outputFile();
     file.writeLine();
-    if (context_.outputFormat() == eHelpOutputFormat_Html)
-    {
-        file.writeLine("
"); - } file.writeLine(); } @@ -446,13 +445,7 @@ void SynopsisFormatter::formatOption(const OptionInfo &option) fullOptionText.append("]"); const int totalLength = fullOptionText.size(); - if (context_.outputFormat() == eHelpOutputFormat_Html) - { - value = replaceAll(value, "<", "<"); - value = replaceAll(value, ">", ">"); - } - - File &file = context_.outputFile(); + File &file = context_.outputFile(); currentLength_ += totalLength; if (currentLength_ >= lineLength_) { @@ -635,17 +628,13 @@ void CommandLineHelpWriter::Impl::formatBugs(const HelpWriterContext &context) return; } context.writeTitle("Known Issues"); - if (context.outputFormat() != eHelpOutputFormat_Console) - { - context.writeTextBlock("[UL]"); - } ConstArrayRef::const_iterator i; for (i = bugs_.begin(); i != bugs_.end(); ++i) { const char *const bug = *i; // TODO: The context should be able to do this also for console output, but // that requires a lot more elaborate parser for the markup. - if (context.outputFormat() == eHelpOutputFormat_Console) + if (context.outputFormat() != eHelpOutputFormat_Man) { TextLineWrapperSettings settings; settings.setIndent(2); @@ -657,13 +646,9 @@ void CommandLineHelpWriter::Impl::formatBugs(const HelpWriterContext &context) } else { - context.writeTextBlock(formatString("[LI]%s", bug)); + context.writeTextBlock(formatString("\n- %s", bug)); } } - if (context.outputFormat() != eHelpOutputFormat_Console) - { - context.writeTextBlock("[ul]"); - } } diff --git a/src/gromacs/gmxana/gmx_chi.c b/src/gromacs/gmxana/gmx_chi.c index 8756ac7bc1..938be0463f 100644 --- a/src/gromacs/gmxana/gmx_chi.c +++ b/src/gromacs/gmxana/gmx_chi.c @@ -1334,7 +1334,7 @@ int gmx_chi(int argc, char *argv[]) { "-binwidth", FALSE, etINT, {&ndeg}, "bin width for histograms (degrees)" }, { "-core_rotamer", FALSE, etREAL, {&core_frac}, - "only the central [TT]-core_rotamer[tt]*(360/multiplicity) belongs to each rotamer (the rest is assigned to rotamer 0)" }, + "only the central [TT]-core_rotamer[tt]\\*(360/multiplicity) belongs to each rotamer (the rest is assigned to rotamer 0)" }, { "-maxchi", FALSE, etENUM, {maxchistr}, "calculate first ndih [GRK]chi[grk] dihedrals" }, { "-normhisto", FALSE, etBOOL, {&bNormHisto}, diff --git a/src/gromacs/gmxana/gmx_current.c b/src/gromacs/gmxana/gmx_current.c index ead28e0a76..18bf347647 100644 --- a/src/gromacs/gmxana/gmx_current.c +++ b/src/gromacs/gmxana/gmx_current.c @@ -890,7 +890,7 @@ int gmx_current(int argc, char *argv[]) "Option [TT]-temp[tt] sets the temperature required for the computation of the static dielectric constant.", "[PAR]", "Option [TT]-eps[tt] controls the dielectric constant of the surrounding medium for simulations using", - "a Reaction Field or dipole corrections of the Ewald summation ([TT]-eps[tt]=0 corresponds to", + "a Reaction Field or dipole corrections of the Ewald summation ([TT]-eps[tt]\\=0 corresponds to", "tin-foil boundary conditions).", "[PAR]", "[TT]-[no]nojump[tt] unfolds the coordinates to allow free diffusion. This is required to get a continuous", diff --git a/src/gromacs/gmxana/gmx_hbond.c b/src/gromacs/gmxana/gmx_hbond.c index ac8e40c5bf..9ab16a282f 100644 --- a/src/gromacs/gmxana/gmx_hbond.c +++ b/src/gromacs/gmxana/gmx_hbond.c @@ -3557,16 +3557,16 @@ int gmx_hbond(int argc, char *argv[]) /* "It is also possible to analyse specific hydrogen bonds with", "[TT]-sel[tt]. This index file must contain a group of atom triplets", "Donor Hydrogen Acceptor, in the following way:[PAR]", + "[TT]", + "[ selected ][BR]", + " 20 21 24[BR]", + " 25 26 29[BR]", + " 1 3 6[BR]", + "[tt][BR]", + "Note that the triplets need not be on separate lines.", + "Each atom triplet specifies a hydrogen bond to be analyzed,", + "note also that no check is made for the types of atoms.[PAR]", */ - "[TT]", - "[ selected ][BR]", - " 20 21 24[BR]", - " 25 26 29[BR]", - " 1 3 6[BR]", - "[tt][BR]", - "Note that the triplets need not be on separate lines.", - "Each atom triplet specifies a hydrogen bond to be analyzed,", - "note also that no check is made for the types of atoms.[PAR]", "[BB]Output:[bb][BR]", "[TT]-num[tt]: number of hydrogen bonds as a function of time.[BR]", diff --git a/src/gromacs/gmxana/gmx_rmsdist.c b/src/gromacs/gmxana/gmx_rmsdist.c index 5616a4136e..6b0a5014e5 100644 --- a/src/gromacs/gmxana/gmx_rmsdist.c +++ b/src/gromacs/gmxana/gmx_rmsdist.c @@ -639,7 +639,7 @@ int gmx_rmsdist(int argc, char *argv[]) "of atom pairs with 1/r^3 and 1/r^6 averaged distance below the", "maximum distance ([TT]-max[tt], which will default to 0.6 in this case)", "can be generated, by default averaging over equivalent hydrogens", - "(all triplets of hydrogens named *[123]). Additionally a list of", + "(all triplets of hydrogens named \\*[123]). Additionally a list of", "equivalent atoms can be supplied ([TT]-equiv[tt]), each line containing", "a set of equivalent atoms specified as residue number and name and", "atom name; e.g.:[PAR]", diff --git a/src/gromacs/gmxana/gmx_trjcat.c b/src/gromacs/gmxana/gmx_trjcat.c index 4a47131b23..0c416b07e5 100644 --- a/src/gromacs/gmxana/gmx_trjcat.c +++ b/src/gromacs/gmxana/gmx_trjcat.c @@ -3,7 +3,7 @@ * * Copyright (c) 1991-2000, University of Groningen, The Netherlands. * Copyright (c) 2001-2004, The GROMACS development team. - * Copyright (c) 2013,2014, by the GROMACS development team, led by + * Copyright (c) 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. @@ -428,8 +428,8 @@ int gmx_trjcat(int argc, char *argv[]) "If the [TT]-demux[tt] option is given, the N trajectories that are", "read, are written in another order as specified in the [TT].xvg[tt] file.", "The [TT].xvg[tt] file should contain something like:[PAR]", - "[TT]0 0 1 2 3 4 5[BR]", - "2 1 0 2 3 5 4[tt][BR]", + "[TT]0 0 1 2 3 4 5[tt][BR]", + "[TT]2 1 0 2 3 5 4[tt][BR]", "Where the first number is the time, and subsequent numbers point to", "trajectory indices.", "The frames corresponding to the numbers present at the first line", diff --git a/src/gromacs/gmxana/gmx_tune_pme.c b/src/gromacs/gmxana/gmx_tune_pme.c index 7660bcf160..31413b2551 100644 --- a/src/gromacs/gmxana/gmx_tune_pme.c +++ b/src/gromacs/gmxana/gmx_tune_pme.c @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2009,2010,2011,2012,2013,2014, by the GROMACS development team, led by + * Copyright (c) 2009,2010,2011,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. @@ -2170,7 +2170,7 @@ int gmx_tune_pme(int argc, char *argv[]) "After calling [gmx-mdrun] several times, detailed performance information", "is available in the output file [TT]perf.out[tt].", "[BB]Note[bb] that during the benchmarks, a couple of temporary files are written", - "(options [TT]-b[tt]*), these will be automatically deleted after each test.[PAR]", + "(options [TT]-b*[tt]), these will be automatically deleted after each test.[PAR]", "If you want the simulation to be started automatically with the", "optimized parameters, use the command line option [TT]-launch[tt].[PAR]", "Basic support for GPU-enabled [TT]mdrun[tt] exists. Give a string containing the IDs", diff --git a/src/gromacs/gmxana/gmx_wham.cpp b/src/gromacs/gmxana/gmx_wham.cpp index 6b82c5d5b3..b39e991970 100644 --- a/src/gromacs/gmxana/gmx_wham.cpp +++ b/src/gromacs/gmxana/gmx_wham.cpp @@ -3146,14 +3146,14 @@ int gmx_wham(int argc, char *argv[]) " reaction coordinate you may also generate your own [TT].pdo[tt] files and", " feed them with the [TT]-ip[tt] option into to [THISMODULE]. The [TT].pdo[tt] file header", " must be similar to the following:[PAR]", - "[TT]# UMBRELLA 3.0[BR]", + "# UMBRELLA 3.0[BR]", "# Component selection: 0 0 1[BR]", "# nSkip 1[BR]", "# Ref. Group 'TestAtom'[BR]", "# Nr. of pull groups 2[BR]", "# Group 1 'GR1' Umb. Pos. 5.0 Umb. Cons. 1000.0[BR]", "# Group 2 'GR2' Umb. Pos. 2.0 Umb. Cons. 500.0[BR]", - "#####[tt][PAR]", + "#####[PAR]", "The number of pull groups, umbrella positions, force constants, and names ", "may (of course) differ. Following the header, a time column and ", "a data column for each pull group follows (i.e. the displacement", diff --git a/src/gromacs/gmxpreprocess/grompp.c b/src/gromacs/gmxpreprocess/grompp.c index abdb5d1456..cd9ede649f 100644 --- a/src/gromacs/gmxpreprocess/grompp.c +++ b/src/gromacs/gmxpreprocess/grompp.c @@ -1447,19 +1447,12 @@ int gmx_grompp(int argc, char *argv[]) "#include [PAR]", "The functioning of these statements in your topology may be modulated by", "using the following two flags in your [TT].mdp[tt] file:[PAR]", - "[TT]define = -DVARIABLE1 -DVARIABLE2[BR]", - "include = -I/home/john/doe[tt][BR]", + "[TT]define = -DVARIABLE1 -DVARIABLE2[tt][BR]", + "[TT]include = -I/home/john/doe[tt][BR]", "For further information a C-programming textbook may help you out.", "Specifying the [TT]-pp[tt] flag will get the pre-processed", "topology file written out so that you can verify its contents.[PAR]", - /* cpp has been unnecessary for some time, hasn't it? - "If your system does not have a C-preprocessor, you can still", - "use [TT]grompp[tt], but you do not have access to the features ", - "from the cpp. Command line options to the C-preprocessor can be given", - "in the [TT].mdp[tt] file. See your local manual (man cpp).[PAR]", - */ - "When using position restraints a file with restraint coordinates", "can be supplied with [TT]-r[tt], otherwise restraining will be done", "with respect to the conformation from the [TT]-c[tt] option.", diff --git a/src/gromacs/onlinehelp/helpwritercontext.cpp b/src/gromacs/onlinehelp/helpwritercontext.cpp index 8ede31c71a..0c8870e787 100644 --- a/src/gromacs/onlinehelp/helpwritercontext.cpp +++ b/src/gromacs/onlinehelp/helpwritercontext.cpp @@ -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. @@ -81,6 +81,8 @@ struct t_sandr //! List of replacements for console output. const t_sandr sandrTty[] = { + { "\\*", "*" }, + { "\\=", "=" }, { "[TT]", "" }, { "[tt]", "" }, { "[BB]", "" }, @@ -133,6 +135,8 @@ const t_sandr sandrTty[] = { //! List of replacements for man page output. const t_sandr sandrMan[] = { + { "\\*", "*" }, + { "\\=", "=" }, { "[TT]", "\\fB" }, { "[tt]", "\\fR" }, { "[BB]", "\\fB" }, @@ -192,22 +196,20 @@ const t_sandr sandrMan[] = { { "[grk]", "" } }; -//! List of replacements for HTML output. -const t_sandr sandrHtml[] = { - { "<", "<" }, - { ">", ">" }, - { "[TT]", "" }, - { "[tt]", "" }, - { "[BB]", "" }, - { "[bb]", "" }, - { "[IT]", "" }, - { "[it]", "" }, +//! List of replacements for reStructuredText output. +const t_sandr sandrRst[] = { + { "[TT]", "``" }, + { "[tt]", "``" }, + { "[BB]", "**" }, + { "[bb]", "**" }, + { "[IT]", "*" }, + { "[it]", "*" }, { "[MATH]", "" }, { "[math]", "" }, - { "[CHEVRON]", "<" }, - { "[chevron]", ">" }, - { "[MAG]", "|" }, - { "[mag]", "|" }, + { "[CHEVRON]", "<" }, + { "[chevron]", ">" }, + { "[MAG]", "\\|" }, + { "[mag]", "\\|" }, { "[INT]", "integral" }, { "[FROM]", " from " }, { "[from]", "" }, @@ -219,7 +221,7 @@ const t_sandr sandrHtml[] = { { "[SUB]", "_" }, { "[sub]", "" }, { "[SQRT]", "sqrt(" }, - { "[sqrt]", ")", }, + { "[sqrt]", ")" }, { "[EXP]", "exp(" }, { "[exp]", ")" }, { "[LN]", "ln(" }, @@ -238,13 +240,11 @@ const t_sandr sandrHtml[] = { { "[sinh]", ")" }, { "[TANH]", "tanh(" }, { "[tanh]", ")" }, - { "[PAR]", "

" }, - { "[BR]", "
" }, - { "[UL]", "

    " }, - { "[LI]", "
  • " }, - { "[ul]", "
" }, - { "[GRK]", "&" }, - { "[grk]", ";" } + { "[PAR]", "\n\n" }, + // [BR] is fundamentally incompatible with rst + { "[BR]", "\n\n"}, + { "[GRK]", "" }, + { "[grk]", "" } }; /*! \brief @@ -429,10 +429,10 @@ void HelpLinks::addLink(const std::string &linkName, case eHelpOutputFormat_Man: replacement = repall(displayName, sandrMan); break; - case eHelpOutputFormat_Html: + case eHelpOutputFormat_Rst: replacement = formatString( - "%s", targetName.c_str(), - repall(displayName, sandrHtml).c_str()); + ":doc:`%s <%s>`", repall(displayName, sandrTty).c_str(), + targetName.c_str()); break; default: GMX_RELEASE_ASSERT(false, "Output format not implemented for links"); @@ -579,9 +579,9 @@ void HelpWriterContext::Impl::processMarkup(const std::string &text, result = repall(result, sandrMan); return wrapper->wrap(result); } - case eHelpOutputFormat_Html: + case eHelpOutputFormat_Rst: { - result = repall(result, sandrHtml); + result = repall(result, sandrRst); result = replaceLinks(result); return wrapper->wrap(result); } @@ -670,8 +670,9 @@ void HelpWriterContext::writeTitle(const std::string &title) const case eHelpOutputFormat_Man: file.writeLine(formatString(".SH %s", toUpperCase(title).c_str())); break; - case eHelpOutputFormat_Html: - file.writeLine(formatString("

%s

", title.c_str())); + case eHelpOutputFormat_Rst: + file.writeLine(title); + file.writeLine(std::string(title.length(), '-')); break; default: GMX_THROW(NotImplementedError( @@ -691,10 +692,6 @@ void HelpWriterContext::writeTextBlock(const std::string &text) const void HelpWriterContext::writeOptionListStart() const { - if (outputFormat() == eHelpOutputFormat_Html) - { - outputFile().writeLine("
"); - } } void HelpWriterContext::writeOptionItem(const std::string &name, @@ -715,15 +712,12 @@ void HelpWriterContext::writeOptionItem(const std::string &name, writeTextBlock(description); file.writeLine(); break; - case eHelpOutputFormat_Html: + case eHelpOutputFormat_Rst: { - std::string substArgs = - substituteMarkupAndWrapToString(TextLineWrapperSettings(), args); - file.writeLine(formatString("
%s %s
", name.c_str(), - substArgs.c_str())); - file.writeLine("
"); - writeTextBlock(description); - file.writeLine("
"); + file.writeLine(formatString("``%s`` %s", name.c_str(), args.c_str())); + TextLineWrapperSettings settings; + settings.setIndent(4); + file.writeLine(substituteMarkupAndWrapToString(settings, description)); break; } default: @@ -734,10 +728,6 @@ void HelpWriterContext::writeOptionItem(const std::string &name, void HelpWriterContext::writeOptionListEnd() const { - if (outputFormat() == eHelpOutputFormat_Html) - { - outputFile().writeLine("
"); - } } } // namespace gmx diff --git a/src/gromacs/onlinehelp/helpwritercontext.h b/src/gromacs/onlinehelp/helpwritercontext.h index 204385b1b7..56f723b013 100644 --- a/src/gromacs/onlinehelp/helpwritercontext.h +++ b/src/gromacs/onlinehelp/helpwritercontext.h @@ -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. @@ -60,7 +60,7 @@ enum HelpOutputFormat { eHelpOutputFormat_Console, //!< Plain text directly on the console. eHelpOutputFormat_Man, //!< Man page. - eHelpOutputFormat_Html, //!< Html output for online manual. + eHelpOutputFormat_Rst, //!< reStructuredText for online manual. eHelpOutputFormat_Other, //!< Used for extensions in other modules. eHelpOutputFormat_NR //!< Used for the number of output formats. }; diff --git a/src/gromacs/trajectoryanalysis/modules/freevolume.cpp b/src/gromacs/trajectoryanalysis/modules/freevolume.cpp index 127a834b1b..b489c2a933 100644 --- a/src/gromacs/trajectoryanalysis/modules/freevolume.cpp +++ b/src/gromacs/trajectoryanalysis/modules/freevolume.cpp @@ -1,7 +1,7 @@ /* * This file is part of the GROMACS molecular simulation package. * - * Copyright (c) 2013,2014, by the GROMACS development team, led by + * Copyright (c) 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. @@ -207,7 +207,8 @@ FreeVolume::initOptions(Options *options, // Add option for selecting a subset of atoms options->addOption(SelectionOption("select") .store(&sel_).defaultSelectionText("all") - .onlyAtoms()); + .onlyAtoms() + .description("Atoms that are considered as part of the excluded volume")); // Add option for the probe radius and initialize it options->addOption(DoubleOption("radius").store(&probeRadius_) diff --git a/src/programs/mdrun/mdrun.cpp b/src/programs/mdrun/mdrun.cpp index cb2457a778..5298cb744d 100644 --- a/src/programs/mdrun/mdrun.cpp +++ b/src/programs/mdrun/mdrun.cpp @@ -178,7 +178,7 @@ int gmx_mdrun(int argc, char *argv[]) "[PAR]", "With option [TT]-maxh[tt] a simulation is terminated and a checkpoint", "file is written at the first neighbor search step where the run time", - "exceeds [TT]-maxh[tt]*0.99 hours. This option is particularly useful in", + "exceeds [TT]-maxh[tt]\\*0.99 hours. This option is particularly useful in", "combination with setting [TT]nsteps[tt] to -1 either in the mdp or using the", "similarly named command line option. This results in an infinite run,", "terminated only when the time limit set by [TT]-maxh[tt] is reached (if any)" -- 2.22.0