From 6fba25686cbf0de7edea819e5028a9b959557a5d Mon Sep 17 00:00:00 2001 From: "M. Eric Irrgang" Date: Thu, 26 Dec 2019 18:45:59 +0300 Subject: [PATCH] Use `todo` Sphinx directive more. Start making "to do"s more actionable. Use the Sphinx `todo` directive to allow special processing. For comment blocks that imply planned activity, convert comment to `todo` directive for more easily discovered and tracked doctree elements. "To do" items should have a clear call to action and some follow through, such as being prohibited in release branches or at least referring to tracked issues, but that is beyond the scope of this change. This change only seeks to make the mass of "to do"s more discoverable. Change-Id: I8cbc06a5a1d78791bc6e9b0a2530632ad09a9380 --- docs/dev-manual/build-system.rst | 16 +++++++---- docs/dev-manual/jenkins.rst | 2 +- docs/dev-manual/overview.rst | 2 +- docs/dev-manual/style.rst | 2 +- docs/dev-manual/tools.rst | 2 +- docs/index.rst | 4 ++- docs/reference-manual/file-formats.rst | 2 +- docs/reference-manual/index.rst | 2 +- docs/reference-manual/preface.rst | 2 +- docs/user-guide/environment-variables.rst | 2 +- docs/user-guide/faq.rst | 34 ++++++++++++++++------- docs/user-guide/force-fields.rst | 2 +- docs/user-guide/index.rst | 4 ++- docs/user-guide/mdp-options.rst | 5 ++-- docs/user-guide/mdrun-performance.rst | 20 +++++++------ docs/user-guide/run-time-errors.rst | 10 +++++-- 16 files changed, 72 insertions(+), 39 deletions(-) diff --git a/docs/dev-manual/build-system.rst b/docs/dev-manual/build-system.rst index 0b0591138d..a98c9e9f84 100644 --- a/docs/dev-manual/build-system.rst +++ b/docs/dev-manual/build-system.rst @@ -111,10 +111,14 @@ This section provides a (currently incomplete) list of cache variables that developers or advanced users can set to affect what CMake generates and/or what will get built. -.. TODO: Figure out where to document basic variables intended for user +.. todo:: + + Figure out where to document basic variables intended for user consumption, and how does it relate to documentation here. -.. TODO: Document the remaining variables below, and identify any variables +.. todo:: + + Document the remaining variables below, and identify any variables missing from the list. Compiler flags @@ -170,7 +174,7 @@ Variables affecting compilation/linking Defaults to ``OFF``, and there should not be any need to change this in a manual build. - .. TODO: This could likely be replaced by a (yet another) build type. + .. todo:: This could likely be replaced by a (yet another) build type. .. cmake:: GMX_BUILD_MDRUN_ONLY @@ -388,7 +392,7 @@ Variables affecting special targets If ``OFF`` (the default), all detection is skipped and the manual cannot be built. - .. TODO: Consider if this is really necessary, or if we could just use + .. todo:: Consider if this is really necessary, or if we could just use GMX_DEVELOPER_BUILD. .. cmake:: GMX_BUILD_TARBALL @@ -442,7 +446,9 @@ Variables affecting special targets External libraries ------------------ -.. TODO: List external libraries used (either from src/external/, or from the +.. todo:: + + List external libraries used (either from src/external/, or from the system), whether they are required or optional, what functionality they provide for Gromacs, and how to control their use. diff --git a/docs/dev-manual/jenkins.rst b/docs/dev-manual/jenkins.rst index 09ac69d383..8ff99a0923 100644 --- a/docs/dev-manual/jenkins.rst +++ b/docs/dev-manual/jenkins.rst @@ -15,7 +15,7 @@ Separate page documents how to interact with the Jenkins UI for these builds: :doc:`releng/jenkins-howto` has information on how to do common things with Jenkins builds. -.. TODO: Add a link to a wiki page about general Jenkins documentation, once +.. todo:: Add a link to a wiki page about general Jenkins documentation, once there is more of that. Pre-submit verification diff --git a/docs/dev-manual/overview.rst b/docs/dev-manual/overview.rst index 4a63fd4cf0..e9bf4c8baa 100644 --- a/docs/dev-manual/overview.rst +++ b/docs/dev-manual/overview.rst @@ -274,7 +274,7 @@ Doxygen documentation See :doc:`doxygen` for details of how the Doxygen documentation is built and organized. -.. TODO: Create a separate page (at the front of the developer guide, and/or at +.. todo:: Create a separate page (at the front of the developer guide, and/or at the main index.rst) that describes the documentation from readers' perspective, and move relevant content there. This should contain just an overview of how the documentation is organized in the source tree. diff --git a/docs/dev-manual/style.rst b/docs/dev-manual/style.rst index 6ef21feadb..761a455524 100644 --- a/docs/dev-manual/style.rst +++ b/docs/dev-manual/style.rst @@ -35,4 +35,4 @@ this page. :doc:`commitstyle` Guidelines for formatting git commits when sending in proposed fixes for code review. -.. TODO: Add more guidelines +.. todo:: Add more guidelines diff --git a/docs/dev-manual/tools.rst b/docs/dev-manual/tools.rst index 8c9dd91a30..1d19150461 100644 --- a/docs/dev-manual/tools.rst +++ b/docs/dev-manual/tools.rst @@ -62,7 +62,7 @@ Redmine Build system ------------ -.. TODO: details, ASAN, others? +.. todo:: details, ASAN, others? CMake Main tool used in the build system. diff --git a/docs/index.rst b/docs/index.rst index 65bd93cfba..002cbe52cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,7 +2,9 @@ Welcome to the |Gromacs| documentation! ======================================= -.. TODO : consolidate at least some of the material in the +.. todo:: + + Consolidate at least some of the material in the Documentation links below into the new user guide, along with all of http://www.gromacs.org/Documentation/Cut-off_schemes, http://www.gromacs.org/Documentation/Acceleration_and_parallelization diff --git a/docs/reference-manual/file-formats.rst b/docs/reference-manual/file-formats.rst index 5567d3a7e4..28ecdc9347 100644 --- a/docs/reference-manual/file-formats.rst +++ b/docs/reference-manual/file-formats.rst @@ -1,7 +1,7 @@ File formats ============ -.. TODO in future patch: update for accuracy, organize better, improve formatting +.. todo:: in future patch: update for accuracy, organize better, improve formatting Summary of file formats ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/reference-manual/index.rst b/docs/reference-manual/index.rst index 44ac3bbf1c..6ef673093a 100644 --- a/docs/reference-manual/index.rst +++ b/docs/reference-manual/index.rst @@ -6,7 +6,7 @@ Reference Manual .. highlight:: bash -.. TODO this needs to be carefully checked that I didn't mess anything up too bad +.. todo:: this needs to be carefully checked that I didn't mess anything up too bad .. ifconfig:: gmx_image_convert == 'possible' diff --git a/docs/reference-manual/preface.rst b/docs/reference-manual/preface.rst index 66dd6b5982..b583b4df96 100644 --- a/docs/reference-manual/preface.rst +++ b/docs/reference-manual/preface.rst @@ -49,7 +49,7 @@ minor release number as your |Gromacs| installation. Citation information -------------------- -.. TODO needs link to ref list +.. todo:: needs link to ref list |GMX_MANUAL_DOI_STRING| diff --git a/docs/user-guide/environment-variables.rst b/docs/user-guide/environment-variables.rst index 5d8f77e59d..4b68280c7f 100644 --- a/docs/user-guide/environment-variables.rst +++ b/docs/user-guide/environment-variables.rst @@ -4,7 +4,7 @@ .. Another useful one-liner to find undocumentedvariables: .. ( export INPUT_FILE=docs/user-guide/environment-variables.rst; GIT_PAGER="cat "; for ss in `for s in $(git grep getenv | sed 's/.*getenv("\(.*\)".*/\1/' | sort -u | grep '^[A-Z]'); do [ $(grep $s $INPUT_FILE -c) -eq 0 ] && echo $s; done `; do git grep $ss ; done ) -.. TODO: still undocumented GMX_QM_GAUSSIAN_NCPUS +.. todo:: still undocumented GMX_QM_GAUSSIAN_NCPUS Environment Variables ===================== diff --git a/docs/user-guide/faq.rst b/docs/user-guide/faq.rst index 352681430a..2c45196c27 100644 --- a/docs/user-guide/faq.rst +++ b/docs/user-guide/faq.rst @@ -111,7 +111,9 @@ Questions regarding simulation methodology You can choose different values for :mdp:`tinit` and :mdp:`init-step`. - .. TODO make links work :ref:`Continuing simulations `. + .. todo:: Add "Continuing simulations" content (label: gmx-cont-simulation) and link. + + e.g. ``:ref:`Continuing simulations `.`` #. Why can't I do conjugate gradient minimization with constraints? @@ -132,16 +134,24 @@ Questions regarding simulation methodology You can either prepare a new :ref:`mdp` file, or extend the simulation time in the original :ref:`tpr` file using :ref:`convert-tpr `. - .. TODO #. How do I complete a crashed simulation? + .. todo:: #. How do I complete a crashed simulation? + + Need gmx-cont-crash doc target. + + .. code-block:: none + + This can be easily achieved using the checkpoint reading + :ref:`available ` in |Gromacs| versions newer than 4. - .. This can be easily achieved using the checkpoint reading - :ref:`available ` in |Gromacs| versions newer than 4. + .. todo:: #. How can I do a simulation at constant pH? - .. TODO #. How can I do a simulation at constant pH? + Need gmx-howto-cph doc target. - .. This is a rather large topic, and you should at least read the short - :ref:`Constant pH How-To ` and all of the literature - included there to get an overview over the topic. + .. code-block:: none + + This is a rather large topic, and you should at least read the short + :ref:`Constant pH How-To ` and all of the literature + included there to get an overview over the topic. #. How should I compute a single-point energy? @@ -176,9 +186,13 @@ Parameterization and Force Fields Analysis and Visualization -------------------------- - .. TODO #. How do I visualize a trajectory? +.. todo:: #. How do I visualize a trajectory? + + gmx-howto-visualize doc target: + + .. code-block:: none - .. Use one of the number of different programs that can visualize + Use one of the number of different programs that can visualize coordinate :ref:`files and trajectories `. #. Why am I seeing bonds being created when I watch the trajectory? diff --git a/docs/user-guide/force-fields.rst b/docs/user-guide/force-fields.rst index 334fd1f1b9..d01f83f2f9 100644 --- a/docs/user-guide/force-fields.rst +++ b/docs/user-guide/force-fields.rst @@ -105,7 +105,7 @@ for 43a1, 43a2, 45a3, 53a5, 53a6 and 54a7. The GROMOS force fields are * GROMOS 43a1p - 43a1 modified to contain SEP (phosphoserine), TPO (phosphothreonine), and PTR (phosphotyrosine) (all PO42- forms), and SEPH, TPOH, PTRH (PO4H- forms). -.. TODO Add new force fields to the list +.. todo:: Add new force fields to the list .. _GROMOS: http://www.igc.ethz.ch/gromos/ .. _reference manual: gmx-manual-parent-dir_ diff --git a/docs/user-guide/index.rst b/docs/user-guide/index.rst index f70b08ad1d..34c6749ee1 100644 --- a/docs/user-guide/index.rst +++ b/docs/user-guide/index.rst @@ -20,7 +20,9 @@ For background on algorithms and implementations, see the |GMX_SOURCE_DOI_STRING| -.. TODO This is going to require more organization now that +.. todo:: + + This is going to require more organization now that we are getting more content available. .. toctree:: diff --git a/docs/user-guide/mdp-options.rst b/docs/user-guide/mdp-options.rst index b9901f7b70..36c2ee104e 100644 --- a/docs/user-guide/mdp-options.rst +++ b/docs/user-guide/mdp-options.rst @@ -2,8 +2,9 @@ See the "run control" section for a working example of the syntax to use when making .mdp entries, with and without detailed documentation for values those entries might take. Everything can - be cross-referenced, see the examples there. TODO Make more - cross-references. + be cross-referenced, see the examples there. + +.. todo:: Make more cross-references. Molecular dynamics parameters (.mdp options) ============================================ diff --git a/docs/user-guide/mdrun-performance.rst b/docs/user-guide/mdrun-performance.rst index 3627211b62..a0f739e349 100644 --- a/docs/user-guide/mdrun-performance.rst +++ b/docs/user-guide/mdrun-performance.rst @@ -997,9 +997,11 @@ An additional set of subcounters can offer more fine-grained inspection of perfo Subcounters are geared toward developers and have to be enabled during compilation. See :doc:`/dev-manual/build-system` for more information. -.. TODO In future patch: - - red flags in log files, how to interpret wallcycle output - - hints to devs how to extend wallcycles +.. todo:: + + In future patch: + - red flags in log files, how to interpret wallcycle output + - hints to devs how to extend wallcycles .. _gmx-mdrun-on-gpu: @@ -1054,7 +1056,7 @@ compatibility (please see the :ref:`section below `). GPU computation of short range nonbonded interactions ..................................................... -.. TODO make this more elaborate and include figures +.. todo:: make this more elaborate and include figures Using the GPU for the short-ranged nonbonded interactions provides the majority of the available speed-up compared to run using only the CPU. @@ -1066,7 +1068,7 @@ this problem and thus reduce the calculation time. GPU accelerated calculation of PME .................................. -.. TODO again, extend this and add some actual useful information concerning performance etc... +.. todo:: again, extend this and add some actual useful information concerning performance etc... |Gromacs| now allows the offloading of the PME calculation to the GPU, to further reduce the load on the CPU and improve usage overlap between @@ -1100,7 +1102,7 @@ Known limitations GPU accelerated calculation of bonded interactions (CUDA only) .............................................................. -.. TODO again, extend this and add some actual useful information concerning performance etc... +.. todo:: again, extend this and add some actual useful information concerning performance etc... |Gromacs| now allows the offloading of the bonded part of the PP workload to a CUDA-compatible GPU. This is treated as part of the PP @@ -1171,9 +1173,9 @@ Performance considerations for GPU tasks #) The only way to know for sure what alternative is best for your machine is to test and check performance. -.. TODO: we need to be more concrete here, i.e. what machine/software aspects to take into consideration, when will default run mode be using PME-GPU and when will it not, when/how should the user reason about testing different settings than the default. +.. todo:: we need to be more concrete here, i.e. what machine/software aspects to take into consideration, when will default run mode be using PME-GPU and when will it not, when/how should the user reason about testing different settings than the default. -.. TODO someone who knows about the mixed mode should comment further. +.. todo:: someone who knows about the mixed mode should comment further. Reducing overheads in GPU accelerated runs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1224,7 +1226,7 @@ Note that assigning fewer resources to :ref:`gmx mdrun` CPU computation involves a tradeoff which may outweigh the benefits of reduced GPU driver overhead, in particular without HyperThreading and with few CPU cores. -.. TODO In future patch: any tips not covered above +.. todo:: In future patch: any tips not covered above Running the OpenCL version of mdrun ----------------------------------- diff --git a/docs/user-guide/run-time-errors.rst b/docs/user-guide/run-time-errors.rst index b47083a4a7..440e566daf 100644 --- a/docs/user-guide/run-time-errors.rst +++ b/docs/user-guide/run-time-errors.rst @@ -85,8 +85,14 @@ the options for obtaining the force field parameters are: * search the primary literature for publications for parameters for the residue that are consistent with the force field that is being used. -.. TODO Once you have determined the parameters and topology for your residue, see - :ref:`adding a residue to a force field ` for instructions on how to proceed. +.. todo:: gmx-add-new-residue doc target + + Need gmx-add-new-residue doc target. + + .. code-block:: none + + Once you have determined the parameters and topology for your residue, see + :ref:`adding a residue to a force field ` for instructions on how to proceed. Long bonds and/or missing atoms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- 2.22.0