#
# 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.
It is used internally by several bash scripts to do copyright-relates tasks,
but can also be invoked directly for some rare use cases.
-See docs/dev-manual/uncrustify.md for more details.
+See docs/dev-manual/uncrustify.rst for more details.
"""
import datetime
#
# 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.
# You can also run git commit --no-verify, but that also disables other hooks,
# such as the Change-Id hook used by Gerrit.
#
-# See docs/dev-manual/uncrustify.md for more details.
+# See docs/dev-manual/uncrustify.rst for more details.
if [ ! -z "$NO_FORMAT_CHECK" ]
then
#
# This file is part of the GROMACS molecular simulation package.
#
-# Copyright (c) 2014, by the GROMACS development team, led by
+# Copyright (c) 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.
# This script runs uncrustify, copyright header checks, or include sorter on
# all applicable files in the source tree.
#
-# See `reformat_all.sh -h` for a brief usage, and docs/dev-manual/uncrustify.md
-# for more details (docs/dev-manual/gmxtree.md for include sorter).
+# See `reformat_all.sh -h` for a brief usage, and docs/dev-manual/uncrustify.rst
+# for more details (docs/dev-manual/gmxtree.rst for include sorter).
function usage() {
echo "usage: reformat_all.sh [-f|--force]"
# This script runs uncrustify and copyright header checks on modified files and
# reports/applies the necessary changes.
#
-# See `uncrustify.sh -h` for a brief usage, and docs/dev-manual/uncrustify.md
+# See `uncrustify.sh -h` for a brief usage, and docs/dev-manual/uncrustify.rst
# for more details.
# Parse command-line arguments
echo "Please set the path to uncrustify using UNCRUSTIFY or"
echo "git config hooks.uncrustifypath."
echo "Note that you need a custom version of uncrustify."
- echo "See docs/dev-manual/uncrustify.md for how to get one."
+ echo "See docs/dev-manual/uncrustify.rst for how to get one."
exit 2
fi
if ! which "$UNCRUSTIFY" 1>/dev/null
-dev-manual/*.md gmx-doxygen
doxygen/DoxygenLayout.xml gmx-doxygen
doxygen/**/*.md gmx-doxygen
set(SPHINX_SOURCE_FILES
index.rst
download.rst
+ dev-manual/index.rst
+ dev-manual/doxygen.rst
+ dev-manual/doxygen-links.rst
+ dev-manual/formatting.rst
+ dev-manual/gmxtree.rst
+ dev-manual/includestyle.rst
+ dev-manual/naming.rst
+ dev-manual/style.rst
+ dev-manual/tools.rst
+ dev-manual/uncrustify.rst
install-guide/index.rst
man/gromacs.7.rst
user-guide/index.rst
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
+exclude_patterns = ['dev-manual/doxygen-links.rst']
if not tags.has('do_man'):
- exclude_patterns = ['man']
+ exclude_patterns += ['man']
else:
- exclude_patterns = ['man/bytopic.rst']
+ exclude_patterns += ['man/bytopic.rst']
# The reST default role (used for this markup: `text`) to use for all
# documents.
+++ /dev/null
-Developer manual {#page_devmanual}
-================
-
-This set of pages contains guidelines, instructions, and explanations related
-to \Gromacs development. The actual code is documented in other parts of this
-Doxygen documentation.
-
-The focus is (at least for now) on things that are tightly tied to the code
-itself, such as helper scripts that reside in the source repository, and may
-require the documentation to be updated in sync. Wiki pages at
-<http://www.gromacs.org/Developer_Zone> contain additional information (much of
-it outdated, though), and can be linked from relevant locations in this guide.
-
- - \subpage page_devtools <br/>
- Documentation for tools used
-
- - \subpage page_devstyle <br/>
- Guidelines to follow when writing new code. For some of the guidelines,
- scripts exist (see \ref page_devtools) to automatically reformat the code
- and/or enforce the guidelines for each commit.
--- /dev/null
+.. _doxygen-page-codelayout: ../doxygen/html-lib/page_codelayout.xhtml
+.. _doxygen-page-modulegraph: ../doxygen/html-lib/page_modulegraph.xhtml
+.. _doxygen-page-unittesting: ../doxygen/html-lib/page_unittesting.xhtml
+.. _doxygen-page-wrapperbinary: ../doxygen/html-lib/page_wrapperbinary.xhtml
--- /dev/null
+Using Doxygen
+=============
+
+This page documents how Doxygen is set up in the |Gromacs| source tree,
+as well as guidelines for adding new Doxygen comments. Examples are included,
+as well as tips and tricks for avoiding Doxygen warnings. The guidelines focus
+on C++ code and other new code that follows the new module layout.
+Parts of the guidelines are still applicable to documenting older code (e.g.,
+within ``gmxlib/`` or ``mdlib/``), in particular the guidelines about formatting
+the Doxygen comments and the use of ``\internal``.
+See `Doxygen documentation on code layout`__ for
+the overall structure of the documentation.
+
+__ doxygen-page-codelayout_
+
+To get started quickly, you only need to read the first two sections to
+understand the overall structure of the documentation, and take a look at the
+examples at the end. The remaining sections provide the details for
+understanding why the examples are the way they are, and for more complex
+situations. They are meant more as a reference to look up solutions for
+particular problems, rather than single-time reading. To understand or find
+individual Doxygen commands, you should first look at Doxygen documentation
+(http://www.stack.nl/~dimitri/doxygen/manual/index.html).
+
+
+Documentation flavors
+---------------------
+
+The |Gromacs| source tree is set up to produce three different levels of Doxygen
+documentation:
+
+1. Public API documentation (suffix ``-user``), which documents functions and
+ classes exported from the library and intended for use outside the |Gromacs|
+ library.
+2. Library API documentation (suffix ``-lib``), which additionally includes
+ functions and classes that are designed to be used from other parts of
+ |Gromacs|, as well as some guidelines that are mostly of interest to
+ developers.
+3. Full documentation (suffix ``-full``), which includes (nearly) all (documented)
+ functions and classes in the source tree.
+
+Each subsequent level of documentation includes all the documentation from the
+levels above it. The suffixes above refer to the suffixes of Doxygen input and
+output files, as well as the name of the output directory. When all the
+flavors have been built, the front pages of the documentation contain links to
+the other flavors, and explain the differences in more detail.
+
+As a general guideline, the public API documentation should be kept free of
+anything that a user linking against an unmodified |Gromacs| does not see.
+In other words, the public API documentation should mainly document the
+contents of installed headers, and provide the necessary overview of using
+those. Also, verbosity requirements for the public API documentation are
+higher: ideally, readers of the documentation could immediately start using the
+API based on the documentation, without any need to look at the implementation.
+
+Similarly, the library API documentation should not contain things that other
+modules in |Gromacs| can or should never call. In particular, anything declared
+locally in source files should be only available in the full documentation.
+Also, if something is documented, and is not identified to be in the library
+API, then it should not be necessary to call that function from outside its
+module.
+
+
+Building the documentation
+--------------------------
+
+If you simply want to see up-to-date documentation, you can go to
+http://jenkins.gromacs.org/job/Documentation_Nightly_master/javadoc/html-lib/index.xhtml
+to see the documentation for the current development version.
+Jenkins also runs Doxygen for all changes pushed to Gerrit for
+release-5-0 and master branches, and the
+resulting documentation can be viewed from the link posted by Jenkins. The
+Doxygen build is marked as unstable if it introduces any Doxygen warnings.
+
+You may need to build the documentation locally if you want to check the
+results after adding/modifying a significant amount of comments. This is
+recommended in particular if you do not have much experience with Doxygen.
+It is a good idea to build with all the different settings to see that the
+result is what you want, and that you do not produce any warnings.
+For local work, it is generally a good idea to set ``GMX_COMPACT_DOXYGEN=ON``
+CMake option, which removes some large generated graphs from the documentation
+and speeds up the process significantly.
+
+All files related to Doxygen reside in the ``docs/doxygen/`` subdirectory in the source
+and build trees. In a freshly checked out source tree, this directory contains
+various ``Doxyfile-*.cmakein`` files. When you run CMake, corresponding files
+``Doxyfile-user``, ``Doxyfile-lib``, and ``Doxyfile-full`` are generated at the
+corresponding location in the build tree. There is also a
+``Doxyfile-common.cmakein``, which is used to produce ``Doxyfile-common``.
+This file contains settings that are shared between all the input files.
+``Doxyfile-compact`` provides the extra settings for ``GMX_COMPACT_DOXYGEN=ON``.
+
+You can run Doxygen directly with one of the generated files (all output will
+be produced under the current working directory), or build one of the
+``doxygen-user``, ``doxygen-lib``, and ``doxygen-full`` targets. The targets run
+Doxygen in a quieter mode and only show the warnings if there were any, and put
+the output under ``docs/html/doxygen/`` in the build tree, so that the Doxygen
+build cooperates with the broader ``webpage`` target.
+The ``doxygen-all`` target builds all three targets with less typing.
+
+The generated documentation is put under ``html-user/``, ``html-lib/``, and/or
+``html-full/``. Open ``index.xhtml`` file from one of
+these subdirectories to start browsing (for |Gromacs| developers, the
+``html-lib/`` is a reasonable starting point). Log files with all Doxygen
+warnings are also produced as ``docs/doxygen/doxygen-*.log``, so you can inspect them after
+the run.
+
+You will need Doxygen 1.8.5 to build the current documentation. Other versions
+may work, but likely also produce warnings. Additionally,
+`graphviz <http://www.graphviz.org>`_ and
+`mscgen <http://www.mcternan.me.uk/mscgen/>`_ are required for some graphs in
+the documentation, and ``latex`` for formulas. Working versions are likely
+available through most package managers. It is possible to build the
+documentation without these tools, but you will see some errors and the related
+figures will be missing from the documentation.
+
+.. _dev-doxygen-guidelines:
+
+General guidelines for Doxygen markup
+-------------------------------------
+
+Doxygen provides quite a few different alternative styles for documenting the
+source code. There are subtleties in how Doxygen treats the different types of
+comments, and this also depends somewhat on the Doxygen configuration. It is
+possible to change the meaning of a comment by just changing the style of
+comment it is enclosed in. To avoid such issues, and to avoid needing to
+manage all the alternatives, a single style throughout the source tree is
+preferable. When it comes to treatment of styles, |Gromacs| uses the default
+Doxygen configuration with one exception: ``JAVADOC_AUTOBRIEF`` is set ``ON`` to
+allow more convenient one-line brief descriptions in C code.
+
+Majority of existing comments in |Gromacs| uses Qt-style comments (``/*!`` and
+``//!`` instead of ``/**`` and ``///``, ``\brief`` instead of ``@brief`` etc.),
+so these should be used also for new documentation. There is a single
+exception for brief comments in C code; see below.
+
+Similarly, existing comments use ``/*!`` for multiline comments in both C and
+C++ code, instead of using multiple ``//!`` lines for C++. The rationale is that
+since the code will be a mixture of both languages for a long time, it is more
+uniform to use similar style in both. Also, since files will likely transition
+from C to C++ gradually, rewriting the comments because of different style
+issues should not generally be necessary. Finally, multi-line ``//!`` comments
+can work differently depending on Doxygen configuration, so it is better to
+avoid that ambiguity.
+
+When adding comments, ensure that a short brief description is always produced.
+This is used in various listings, and should briefly explain the purpose of the
+method without unnecessarily expanding those lists.
+The basic guideline is to start all comment blocks with ``\brief`` (possibly
+after some other Doxygen commands).
+If you want to avoid the ``\brief`` for one-liners, you can use ``//!``, but the
+description must fit on a single line; otherwise, it is not interpreted as a
+brief comment. Note in particular that a simple ``/*!`` without a ``\brief``
+does not produce a brief description.
+Also note that ``\brief`` marks the whole following paragraph as a brief
+description, so you should insert an empty line after the intended brief
+description.
+
+In C code, ``//`` comments must be avoided because some compilers do not like
+them. If you want to avoid the ``\brief`` for one-liners in C code, use
+``/**`` instead of ``//!``. If you do this, the brief description should not
+contain unescaped periods except at the end. Because of this, you should
+prefer ``//!`` in C++ code.
+
+Put the documentation comments in the header file that contains the
+declaration, if such a header exists.
+Implementation-specific comments that do not influence how a method
+is used can go into the source file, just before the method definition, with an
+``\internal`` tag in the beginning of the comment block. Doxygen-style comments
+within functions are not generally usable.
+
+At times, you may need to exclude some part of a header or a source file such
+that Doxygen does not see it at all. In general, you should try to avoid this,
+but it may be necessary to remove some functions that you do not want to appear
+in the public API documentation, and which would generate warnings if left
+undocumented, or to avoid Doxygen warnings from code it does not understand.
+Prefer ``\cond`` and ``\endcond`` to do this. If ``\cond`` does not work for
+you, you can also use ``#ifndef DOXYGEN``. If you exclude a class method in
+a header, you also need to exclude it in the source code to avoid warnings.
+
+
+|Gromacs| specifics
+-------------------
+
+The general guidelines on the style of Doxygen comments were given above.
+This section introduces |Gromacs| specific constructs currently used in Doxygen
+documentation, as well as how |Gromacs| uses Doxygen groups to organize the
+documentation.
+
+Some consistency checks are done automatically using custom scripts.
+See :doc:`gmxtree` for details.
+
+Controlling documentation visibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To control in which level of documentation a certain function appears, three
+different mechanisms are used:
+
+* Global Doxygen configuration. This is mainly used to include
+ declarations local to source files only in the full documentation.
+ You can find the details from the ``Doxyfile-*.cmakein`` files, and some of
+ them are also mentioned below on individual code constructs.
+* The standard Doxygen command ``\internal`` marks the documentation to be only
+ extracted into the full documentation (``INTERNAL_DOCS`` is ``ON`` only for the
+ full documentation). This should be used as a first command in a comment
+ block to exclude all the documentation. It is possible to use ``\internal``
+ and ``\endinternal`` to exclude individual paragraphs, but ``\if internal``
+ is preferred (see below).
+ In addition, |Gromacs|-specific custom Doxygen command ``\libinternal`` is
+ provided, which should be used the same way to exclude the documentation from
+ the public API documentation. This command expands to either ``\internal``
+ or to a no-op, depending on the documentation level.
+* Doxygen commands ``\if`` and ``\cond`` can be used with section names
+ ``libapi`` and ``internal`` to only include the documentation in library API and
+ the full documentation, respectively. ``libapi`` is also defined in the full
+ documentation. These are declared using ``ENABLED_SECTIONS`` in the Doxygen
+ configuration files.
+
+Examples of locations where it is necessary to use these explicit commands are
+given below in the sections on individual code constructs.
+
+Modules as Doxygen groups
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As described in `Doxygen documentation for code layout`__
+each subdirectory under ``src/gromacs/``
+represents a *module*, i.e., a somewhat coherent collection of routines.
+Doxygen cannot automatically generate a list of routines in a module; it only
+extracts various alphabetical indexes that contain more or less all documented
+functions and classes. To help reading the documentation, the routines for a
+module should be visible in one place.
+
+__ doxygen-page-codelayout_
+
+|Gromacs| uses Doxygen groups to achieve this: for each documented module, there
+is a ``\defgroup`` definition for the module, and all the relevant classes and
+functions need to be manually added to this group using ``\ingroup`` and
+``\addtogroup``.
+The group page also provides a natural place for overview documentation about
+the module, and can be navigated to directly from the "Modules" tab in the
+generated documentation.
+
+Some notes about using ``\addtogroup`` are in order:
+
+* ``\addtogroup`` only adds the elements that it directly contains into the
+ group. If it contains a namespace declaration, only the namespace is added
+ to the group, but none of the namespace contents are. For this reason,
+ ``\addtogroup`` should go within the innermost scope, around the members that
+ should actually be added.
+* If the module should not appear in the public API documentation, its
+ definition (``\defgroup``) should be prefixed with a ``\libinternal``.
+ In this case, also all ``\addtogroup`` commands for this module should be
+ similarly prefixed. Otherwise, they create the group in the public API
+ documentation, but without any of the content from the ``\defgroup``
+ definition. This may also cause the contents of the ``\addtogroup`` section
+ to appear in the public API documentation, even if it otherwise would not.
+
+Public API and library API groups
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the module groups, two fixed groups are provided:
+``group_publicapi`` and ``group_libraryapi``. Classes and files can be added to
+these groups using |Gromacs| specific custom ``\inpublicapi`` and
+``\inlibraryapi`` commands. The generated group documentation pages are not
+very useful, but annotated classes and files show the API definition under the
+name, making this information more easily accessible. These commands in
+file-level comments are also used for some automatic intermodule dependency
+validation (see below).
+
+Note that functions, enumerations, and other entities that do not have a
+separate page in the generated documentation can only belong to one group;
+in such a case, the module group is preferred over the API group.
+
+
+Documenting specific code constructs
+------------------------------------
+
+This section describes the techical details and some tips and tricks for
+documenting specific code constructs such that useful documentation is
+produced. If you are wondering where to document a certain piece of
+information, see the documentation structure section in
+`Doxygen documentation for code layout`__.
+The focus of the documentation should be on the overview content: Doxygen pages
+and the module documentation. An experienced developer can relatively easily
+read and understand individual functions, but the documentation should help
+in getting the big picture.
+
+__ doxygen-page-codelayout_
+
+Doxygen pages
+^^^^^^^^^^^^^
+
+The pages that are accessible through navigation from the front page are
+written using Markdown and are located under ``docs/doxygen/``. Each page should be
+placed in the page hierarchy by making it a subpage of another page, i.e., it
+should be referenced once using ``\subpage``. ``mainpage.md`` is the root of the
+hierarchy.
+
+There are two subdirectories, ``user/`` and ``lib/``, determining the highest
+documentation level where the page appears. If you add pages to ``lib/``, ensure
+that there are no references to the page from public API documentation.
+``\if libapi`` can be used to add references in content that is otherwise
+public.
+Generally, the pages should be on a high enough level and provide overview
+content that is useful enough such that it is not necessary to exclude them
+from the library API documentation.
+
+Modules
+^^^^^^^
+
+For each module, decide on a header file that is the most important one for
+that module (if there is no self-evident header, it may be better to designate,
+e.g., ``module-doc.h`` for this purpose, but this is currently not done for any
+module). This header should contain the ``\defgroup`` definition for the
+module. The name of the group should be :file:`module_{name}`, where *name*
+is the name of the subdirectory that hosts the module.
+
+The module should be added to an appropriate group (see ``docs/doxygen/misc.cpp`` for
+definitions) using ``\ingroup`` to organize the "Modules" tab in the generated
+documentation.
+
+One or more contact persons who know about the contents of the module should be
+listed using ``\author`` commands. This provides a point of contact if one
+has questions.
+
+Classes/structs
+^^^^^^^^^^^^^^^
+
+Classes and structs in header files appear always in Doxygen documentation,
+even if their enclosing file is not documented. So start the documentation
+blocks of classes that are not part of the public API with ``\internal`` or
+``\libinternal``. Classes declared locally in source files or in unnamed
+namespaces only appear in the full documentation.
+
+If a whole class is not documented, this does not currently generate any
+warning. The class is simply exluded from the documentation. But if a member
+of a documented class is not documented, a warning is generated. Guidelines for
+documenting free functions apply to methods of a class as well.
+
+For base classes, the API classification (``\inpublicapi`` or
+``\inlibraryapi``) should be based on where the class is meant to be
+subclassed. The visibility (``\internal`` or ``\libinternal``), in contrast,
+should reflect the API classification of derived classes such that the base
+class documentation is always generated together with the derived classes.
+
+For classes that are meant to be subclassed and have protected members, the
+protected members should only appear at the documentation level where the class
+is meant to be subclassed. For example, if a class is meant to be subclassed
+only within a module, the protected members should only appear in the
+full documentation. This can be accomplished using ``\cond`` (note that you
+will need to add the ``\cond`` command also to the source files to hide the
+same methods from Doxygen, otherwise you will get confusing warnings).
+
+Methods/functions/enums/macros
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These items do not appear in the documentation unless their enclosing scope is
+documented. For class members, the scope is the class; otherwise, it is the
+namespace if one exists, or the file. An ``\addtogroup`` can also define a
+scope if the group has higher visibility than the scope outside it.
+So if a function is not within a namespace (mostly applicable to C code) and
+has the same visibility as its enclosing file, it is not necessary to add a
+``\internal`` or ``\libinternal``.
+
+Static functions are currently extracted for all documentation flavors to allow
+headers to declare ``static inline`` functions (used in, for example, math code).
+Functions in anonymous namespaces are only extracted into the full
+documentation. Together with the above rules, this means that you should avoid
+putting a ``static`` function within a documented namespace, even within source
+files, or it may inadvertently appear in the public API documentation.
+
+If you want to exclude an item from the documentation, you need to put in
+inside a ``\cond`` block such that Doxygen does not see it.
+Otherwise, a warning for an undocumented function is generated. You need to
+enclose both the declaration and the definition with ``\cond``.
+
+Files
+^^^^^
+
+Each documented file should start with a documentation block (right after the
+copyright notice) that documents the file. See the examples section for exact
+formatting. Things to note:
+
+* Please do not specify the file name explicitly after ``\file``. By default,
+ a file comment applies to the file it is contained in, and an explicit file
+ name only adds one more thing that can get out of date.
+* ``\brief`` cannot appear on the same line as the ``\file``, but should be on
+ the next line.
+* ``\internal`` or ``\libinternal`` should indicate where the header is visible.
+ As a general guideline, all installed headers should appear in the public API
+ documentation, i.e., not contain these commands. If nothing else, then to
+ document that it does not contain any public API functions. Headers that
+ declare anything in the library API should be marked with ``\libinternal``,
+ and the rest with ``\internal``.
+* All source files, as well as most test files, should be documented with
+ ``\internal``, since they do not provide anything to public or library API,
+ and this avoids unintentionally extracting things from the file into those
+ documentations. Shared test files used in tests from other modules should be
+ marked with ``\libinternal``.
+* ``\inpublicapi`` or ``\inlibraryapi`` should be used to indicate where the
+ header is meant to be directly included.
+* As with modules, one or more contact persons should be listed with ``\author``.
+ If you make significant modifications or additions to a file, consider adding
+ an ``\author`` line for yourself.
+
+Directories
+^^^^^^^^^^^
+
+Directory documentation does not typically contain useful information beyond a
+possible brief description, since they correspond very closely to modules, and
+the modules themselves are documented. A brief description is still useful to
+provide a high-level overview of the source tree on the generated "Files" page.
+A reference to the module is typically sufficient as a brief description for a
+directory. All directories are currently documented in
+``docs/doxygen/directories.cpp``.
+
+
+Examples
+--------
+
+.. highlight:: c++
+
+Basic C++
+^^^^^^^^^
+
+Here is an example of documenting a C++ class and its containing header file.
+Comments in the code and the actual documentation explain the used Doxygen
+constructs. ::
+
+ /*! \libinternal \file
+ * \brief
+ * Declares gmx::MyClass.
+ *
+ * More details. The documentation is still extracted for the class even if
+ * this whole comment block is missing.
+ *
+ * \author Example Author <example@author.com>
+ * \inlibraryapi
+ * \ingroup module_mymodule
+ */
+
+ namespace gmx
+ {
+
+ /*! \libinternal
+ * \brief
+ * Brief description for the class.
+ *
+ * More details. The \libinternal tag is required for classes, since they are
+ * extracted into the documentation even in the absence of documentation for
+ * the enclosing scope.
+ * The \libinternal tag is on a separate line because of a bug in Doxygen
+ * 1.8.5 (only affects \internal, but for clarity it is also worked around
+ * here).
+ *
+ * \inlibraryapi
+ * \ingroup module_mymodule
+ */
+ class MyClass
+ {
+ public:
+ // Trivial constructors or destructors do not require documentation.
+ // But if a constructor takes parameters, it should be documented like
+ // methods below.
+ MyClass();
+ ~MyClass();
+
+ /*! \brief
+ * Brief description for the method.
+ *
+ * \param[in] param1 Description of the first parameter.
+ * \param[in] param2 Description of the second parameter.
+ * \returns Description of the return value.
+ * \throws std::bad_alloc if out of memory.
+ *
+ * More details describing the method. It is not an error to put this
+ * above the parameter block, but most existing code has it here.
+ */
+ int myMethod(int param1, const char *param2) const;
+
+ //! Brief description for the accessor.
+ int simpleAccessor() const { return var_; }
+ /*! \brief
+ * Alternative, more verbose way of specifying a brief description.
+ */
+ int anotherAccessor() const;
+ /*! \brief
+ * Brief description for another accessor that is so long that it does
+ * not conveniently fit on a single line cannot be specified with //!.
+ */
+ int secondAccessor() const;
+
+ private:
+ // Private members (whether methods or variables) are currently ignored
+ // by Doxygen, so they don't need to be documented. Documentation
+ // doesn't hurt, though.
+ int var_;
+ };
+
+ } // namespace gmx
+
+Basic C
+^^^^^^^
+
+Here is another example of documenting a C header file (so avoiding all
+C++-style comments), and including free functions. It also demonstrates the use
+of ``\addtogroup`` to add multiple functions into a module group without repeated
+``\ingroup`` tags. ::
+
+ /*! \file
+ * \brief
+ * Declares a collection of functions for performing a certain task.
+ *
+ * More details can go here.
+ *
+ * \author Example Author <example@author.com>
+ * \inpublicapi
+ * \ingroup module_mymodule
+ */
+
+ /*! \addtogroup module_mymodule */
+ /*! \{ */
+
+ /*! \brief
+ * Brief description for the data structure.
+ *
+ * More details.
+ *
+ * \inpublicapi
+ */
+ typedef struct {
+ /** Brief description for member. */
+ int member;
+ int second; /**< Brief description for the second member. */
+ /*! \brief
+ * Brief description for the third member.
+ *
+ * Details.
+ */
+ int third;
+ } gmx_mystruct_t;
+
+ /*! \brief
+ * Performs a simple operation.
+ *
+ * \param[in] value Input value.
+ * \returns Computed value.
+ *
+ * Detailed description.
+ * \inpublicapi cannot be used here, because Doxygen only allows a single
+ * group for functions, and module_mymodule is the preferred group.
+ */
+ int gmx_function(int value);
+
+ /* Any . in the brief description should be escaped as \. */
+ /** Brief description for this function. */
+ int gmx_simple_function();
+
+ /*! \} */
+
+Scoping and visibility rules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The rules where Doxygen expects something to be documented, and when are
+commands like ``\internal`` needed, can be complex. The examples below
+describe some of the pitfalls. ::
+
+ /*! \libinternal \file
+ * \brief
+ * ...
+ *
+ * The examples below assume that the file is documented like this:
+ * with an \libinternal definition at the beginning, with an intent to not
+ * expose anything from the file in the public API. Things work similarly for
+ * the full documentation if you replace \libinternal with \internal
+ * everywhere in the example.
+ *
+ * \ingroup module_example
+ */
+
+
+ /*! \brief
+ * Brief description for a free function.
+ *
+ * A free function is not extracted into the documentation unless the enclosing
+ * scope (in this case, the file) is. So a \libinternal is not necessary.
+ */
+ void gmx_function();
+
+ // Assume that the module_example group is defined in the public API.
+
+ //! \addtogroup module_example
+ //! \{
+
+ //! \cond libapi
+ /*! \brief
+ * Brief description for a free function within \addtogroup.
+ *
+ * In this case, the enclosing scope is actually the module_example group,
+ * which is documented, so the function needs to be explicitly excluded.
+ * \\libinternal does not work, since it would produce warnings about an
+ * undocumented function, so the whole declaration is hidden from Doxygen.
+ */
+ void gmx_function();
+ //! \endcond
+
+ //! \}
+
+ // For modules that are only declared in the library API, \addtogroup
+ // cannot be used without an enclosing \cond. Otherwise, it will create
+ // a dummy module with the identifier as the name...
+
+ //! \cond libapi
+ //! \addtogroup module_libmodule
+ //! \{
+
+ /*! \brief
+ * Brief description.
+ *
+ * No \libinternal is necessary here because of the enclosing \cond.
+ */
+ void gmx_function();
+
+ //! \}
+ //! \endcond
+
+ // An alternative to the above is use this, if the enclosing scope is only
+ // documented in the library API:
+
+ //! \libinternal \addtogroup module_libmodule
+ //! \{
+
+ //! Brief description.
+ void gmx_function()
+
+ //! \}
+
+ /*! \libinternal \brief
+ * Brief description for a struct.
+ *
+ * Documented structs and classes from headers are always extracted into the
+ * documentation, so \libinternal is necessary to exclude it.
+ * Currently, undocumented structs/classes do not produce warnings, so \cond
+ * is not necessary.
+ */
+ struct t_example
+ {
+ int member1; //!< Each non-private member should be documented.
+ bool member2; //!< Otherwise, Doxygen will produce warnings.
+ };
+
+ // This namespace is documented in the public API.
+ namespace gmx
+ {
+
+ //! \cond libapi
+ /*! \brief
+ * Brief description for a free function within a documented namespace.
+ *
+ * In this case, the enclosing scope is the documented namespace,
+ * so a \cond is necessary to avoid warnings.
+ */
+ void gmx_function();
+ //! \endcond
+
+ /*! \brief
+ * Class meant for subclassing only within the module, but the subclasses will
+ * be public.
+ *
+ * This base class still provides public methods that are visible through the
+ * subclasses, so it should appear in the public documentation.
+ * But it is not marked with \inpublicapi.
+ */
+ class BaseClass
+ {
+ public:
+ /*! \brief
+ * A public method.
+ *
+ * This method also appears in the documentation of each subclass in
+ * the public and library API docs.
+ */
+ void method();
+
+ protected:
+ // The \cond is necessary to exlude this documentation from the public
+ // API, since the public API does not support subclassing.
+ //! \cond internal
+ //! A method that only subclasses inside the module see.
+ void methodForSubclassToCall();
+
+ //! A method that needs to be implemented by subclasses.
+ virtual void virtualMethodToImplement() = 0;
+ //! \endcond
+ };
+
+ } // namespace gmx
+
+Module documentation
+^^^^^^^^^^^^^^^^^^^^
+
+Documenting a new module should place a comment like this in a central header
+for the module, such that the "Modules" tab in the generated documentation can
+be used to navigate to the module. ::
+
+ /*! \defgroup module_example "Example module (example)"
+ * \ingroup group_utilitymodules
+ * \brief
+ * Brief description for the module.
+ *
+ * Detailed description of the module. Can link to a separate Doxygen page for
+ * overview, and/or describe the most important headers and/or classes in the
+ * module as part of this documentation.
+ *
+ * For modules not exposed publicly, \libinternal can be added at the
+ * beginning (before \defgroup).
+ *
+ * \author Author Name <author.name@email.com>
+ */
+
+ // In other code, use \addtogroup module_example and \ingroup module_example to
+ // add content (classes, functions, etc.) onto the module page.
+
+Common mistakes
+^^^^^^^^^^^^^^^
+
+The most common mistake, in particular in C code, is to forget to document the
+file. This causes Doxygen to ignore most comments in the file, so it
+does not validate the contents of the comments either, nor is it possible to
+actually check how the generated documentation looks like.
+
+The following examples show some other common mistakes (and some less common)
+that do not produce correct documentation, as well as Doxygen "features"/bugs
+that can be confusing.
+
+* The struct itself is not documented; other comments within the declaration
+ are ignored. ::
+
+ struct t_struct {
+
+ // The comment tries to document both members at once, but it only
+ // applies to the first. The second produces warnings about missing
+ // documentation (if the enclosing struct was documented).
+
+ //! Angle parameters.
+ double alpha, beta;
+ };
+
+* This does not produce any brief documentation.
+ An explicit ``\brief`` is required, or ``//!`` (C++) or ``/** */`` (C)
+ should be used. ::
+
+ /*! Brief comment. */
+ int gmx_function();
+
+* This does not produce any documentation at all, since a ``!`` is missing at
+ the beginning. ::
+
+ /* \brief
+ * Brief description.
+ *
+ * More details.
+ */
+ int gmx_function();
+
+* This puts the whole paragraph into the brief description.
+ A short description is preferable, separated by an empty line from the rest
+ of the text. ::
+
+ /*! \brief
+ * Brief description. The description continues with all kinds of details about
+ * what the function does and how it should be called.
+ */
+ int gmx_function();
+
+* This may be a Doxygen bug, but this does not produce any brief description. ::
+
+ /** \internal Brief description. */
+ int gmx_function();
+
+* If the first declaration below appears in a header, and the second in a
+ source file, then Doxygen does not associate them correctly and complains
+ about missing documentation for the latter. The solution is to explicitly
+ add a namespace prefix also in the source file, even though the compiler
+ does not require it. ::
+
+ // Header file
+ //! Example function with a namespace-qualified parameter type.
+ int gmx_function(const gmx::SomeClass ¶m);
+
+ // Source file
+ using gmx::SomeClass;
+
+ int gmx_function(const SomeClass ¶m);
+
+* This puts the namespace into the mentioned module, instead of the contents
+ of the namespace. ``\addtogroup`` should go within the innermost scope. ::
+
+ //! \addtogroup module_example
+ //! \{
+
+ namespace gmx
+ {
+
+ //! Function intended to be part of module_example.
+ int gmx_function();
+
+ }
+
+Existing code
+^^^^^^^^^^^^^
+
+More examples you can find by looking at existing code in the source tree. In
+particular new C++ code such as that in the ``src/gromacs/analysisdata/`` and
+``src/gromacs/options/`` subdirectories contains a large amount of code
+documented mostly along these guidelines. Some comments in
+``src/gromacs/selection/`` (in particular, any C-like code) predate the
+introduction of these guidelines, so those are not the best examples.
+
+.. include:: doxygen-links.rst
+++ /dev/null
-Guidelines for code formatting {#page_devstyle_formatting}
-==============================
-
-The following list provides the general formatting/indentation rules for
-\Gromacs code (C/C++):
- * Basic indentation is four spaces.
- * Keep lines at a reasonable length. There is no hard limit, but use 80
- characters as a guideline. If you end up indenting very deeply,
- consider splitting the code into functions.
- * Do not use tabs, only spaces. Most editors can be configured to generate
- spaces even when pressing tab. Tabs (in particular when mixed with spaces)
- easily break indentation in contexts where settings are not exactly equal
- (e.g., in `git diff` output).
- * No trailing whitespace.
- * Use braces always for delimiting blocks, even when there is only a single
- statement in an `if` block or similar.
- * Put braces on their own lines. The only exception is short one-line inline
- functions in C++ classes, which can be put on a single line.
- * Use spaces liberally.
- * `extern "C"` and `namespace` blocks are not indented, but all others
- (including `class` and `switch` bodies) are.
-
-Additionally:
- * All source files and other non-trivial scripts should contain a copyright
- header with a predetermined format and license information (check existing
- files). Copyright holder should be "the GROMACS development team" for the
- years where the code has been in the \Gromacs source repository, but earlier
- years can hold other copyrights.
- * Whenever you update a file, you should check that the current year is listed
- as a copyright year.
-
-Most of the above guidelines are enforced using uncrustify, an automatic source
-code formatting tool. The copyright guidelines are enforced by a separate
-Python script. See \ref page_dev_uncrustify for details. Note that due to the
-nature of uncrustify (it only does all-or-nothing formatting), it enforces
-several additional formatting rules in addition to those above.
-
-Enforcing a consistent formatting has a few advantages:
- * No one needs to manually review code for most of these formatting issues,
- and people can focus on content.
- * A separate automatic script (see below) can be applied to re-establish the
- formatting after refactoring like renaming symbols or changing some
- parameters, without needing to manually do it all.
--- /dev/null
+Guidelines for code formatting
+==============================
+
+The following list provides the general formatting/indentation rules for
+|Gromacs| code (C/C++):
+
+* Basic indentation is four spaces.
+* Keep lines at a reasonable length. There is no hard limit, but use 80
+ characters as a guideline. If you end up indenting very deeply,
+ consider splitting the code into functions.
+* Do not use tabs, only spaces. Most editors can be configured to generate
+ spaces even when pressing tab. Tabs (in particular when mixed with spaces)
+ easily break indentation in contexts where settings are not exactly equal
+ (e.g., in ``git diff`` output).
+* No trailing whitespace.
+* Use braces always for delimiting blocks, even when there is only a single
+ statement in an ``if`` block or similar.
+* Put braces on their own lines. The only exception is short one-line inline
+ functions in C++ classes, which can be put on a single line.
+* Use spaces liberally.
+* ``extern "C"`` and ``namespace`` blocks are not indented, but all others
+ (including ``class`` and ``switch`` bodies) are.
+
+Additionally:
+
+* All source files and other non-trivial scripts should contain a copyright
+ header with a predetermined format and license information (check existing
+ files). Copyright holder should be "the GROMACS development team" for the
+ years where the code has been in the |Gromacs| source repository, but earlier
+ years can hold other copyrights.
+* Whenever you update a file, you should check that the current year is listed
+ as a copyright year.
+
+Most of the above guidelines are enforced using uncrustify, an automatic source
+code formatting tool. The copyright guidelines are enforced by a separate
+Python script. See :doc:`uncrustify` for details. Note that due to the
+nature of uncrustify (it only does all-or-nothing formatting), it enforces
+several additional formatting rules in addition to those above.
+
+Enforcing a consistent formatting has a few advantages:
+
+* No one needs to manually review code for most of these formatting issues,
+ and people can focus on content.
+* A separate automatic script (see below) can be applied to re-establish the
+ formatting after refactoring like renaming symbols or changing some
+ parameters, without needing to manually do it all.
+++ /dev/null
-Source tree checker scripts {#page_dev_gmxtree}
-===========================
-
-There is a set of Python scripts, currently under `docs/doxygen/`, that check
-various aspects of the source tree for consistency. The script is based on
-producing an abstract representation of the source tree from various sources:
- * List of files in the source tree (for overall layout of the source tree)
- * List of installed headers (extracted from the generated build system)
- * git attributes (to limit the scope of some checks)
- * Doxygen XML documentation:
- * For tags about public/private nature of documented headers and other
- constructs
- * For actual documented constructs, to check them for consistency
- * Hard-coded knowledge about the \Gromacs source tree layout
-
-This representation is then used for various purposes:
- * Checking Doxygen documentation elements for common mistakes: missing brief
- descriptions, mismatches in file and class visibility, etc.
- * Checking for consistent usage and documentation of headers: e.g., a header
- that is documented as internal to a module should not be used outside that
- module.
- * Checking for module-level cyclic dependencies
- * Checking for consistent style and order of \#include directives
- (see \ref page_devstyle_includes)
- * Actually sorting and reformatting \#include directives to adhere to the
- checked style
- * Generating dependency graphs between modules and for files within modules
-
-The checks are run as part of a single `check-source` target, but are described
-in separate sections below. In addition to printing the issues to `stderr`,
-the script also writes them into `docs/doxygen/check-source.log` for later
-inspection. Jenkins runs the checks as part of the Documentation job, and the
-build is marked unstable if any issues are found.
-
-For correct functionality, the scripts depend on correct usage of Doxygen
-annotations described in \ref page_doxygen, in particular the visibility and
-API definitions in file-level comments.
-
-For some false positives from the script, the suppression mechanism described
-below is the easiest way to silence the script, but otherwise the goal would be
-to minimize the number of suppressions.
-
-The scripts require Python 2.7 (other versions may work, but have not been
-tested).
-
-To understand how the scripts work internally, see comments in the Python
-source files under `docs/doxygen/`.
-
-Checker details
-===============
-
-The `check-source` target currently checks for a few different types of issues.
-These are listed in detail below, mainly related to documentation and include
-dependencies. Note in particular that the include dependency checks are much
-stricter for code in modules/directories that are documented with a
-\c \\defgroup: all undocumented code is assumed to be internal to such modules.
-The rationale is that such code has gotten some more attention, and some effort
-should also have been put into defining what is the external interface of the
-module and documenting it.
-
-* For all Doxygen documentation (currently does not apply for members that do
- not appear in the documentation):
- * If a member has documentation, it should have a brief description.
- * A note is issued for in-body documentation for functions, since this is
- ignored by our current settings.
- * If a class has documentation, it should have public documentation only if
- it appears in an installed header.
- * If a class and its containing file has documentation, the class
- documentation should not be visible if the file documentation is not.
-* For all files:
- * Consistent usage of
-
- #include "..." // This should be used for Gromacs headers
-
- and
-
- #include <...> // This should be used for system and external headers
-
- * Installed headers must not include non-installed headers.
- * All source files must include "gmxpre.h" as the first header.
- * A source/header file should include "config.h" if and only if it uses a
- macro declared there.
- * If the file has a git attribute to identify it as a candidate for include
- sorting, the include sorter described below should not produce any
- changes (i.e., the file should follow \ref page_devstyle_includes).
-* For documented files:
- * Installed headers should have public documentation, and other files should
- not.
- * The API level specified for a file should not be higher than where its
- documentation is visible. For example, only publicly documented headers
- should be specified as part of the public API.
- * If an \c \\ingroup `module_foo` exists, it should match the subdirectory
- that the file is actually part of in the file system.
- * If a \c \\defgroup `module_foo` exists for the subdirectory where the file
- is, the file should contain \c \\ingroup `module_foo`.
- * Files should not include other files whose documentation visibility is
- lower (if the included file is not documented, the check is skipped).
-* For files that are part of documented modules
- (\c \\defgroup `module_foo` exists for the subdirectory), or are explicitly
- documented to be internal or in the library API:
- * Such files should not be included from outside their module if they are
- undocumented (for documented modules) or are not specified as part of
- library or public API.
-* For all modules:
- * There should not be cyclic include dependencies between modules.
-
-As a side effect, the XML extraction makes Doxygen parse all comments in the
-code, even if they do not appear in the documentation. This can reveal latent
-issues in the comments, like invalid Doxygen syntax. The messages from the XML
-parsing are stored in `docs/doxygen/doxygen-xml.log` in the build tree, similar to
-other Doxygen runs.
-
-Suppressing issues
-------------------
-
-The script is not currently perfect (either because of unfinished
-implementation, or because Doxygen bugs or incompleteness of the Doxygen XML
-output), and the current code also contains issues that the script detects, but
-the authors have not fixed. To allow the script to still be used,
-`doxygen/suppressions.txt` contains a list of issues that are filtered out from
-the report. The syntax is simple:
-
- <file>: <text>
-
-where `<file>` is a path to the file that reports the message, and `<text>` is
-the text reported. Both support `*` as a wildcard. If `<file>` is empty, the
-suppression matches only messages that do not have an associated file.
-`<file>` is matched against the trailing portion of the file name to make it
-work even though the script reports absolute paths.
-Empty lines and lines starting with `#` are ignored.
-
-To add a suppression for an issue, the line that reports the issue can be
-copied into `suppressions.txt`, and the line number (if any) removed. If the
-issue does not have a file name (or a pseudo-file) associated, a leading `:`
-must be added. To cover many similar issues, parts of the line can then be
-replaced with wildcards.
-
-A separate suppression mechanism is in place for cyclic dependencies: to
-suppress a cycle between moduleA and moduleB, add a line with format
-
- moduleA -> moduleB
-
-into `doxygen/cycle-suppressions.txt`. This suppresses all cycles that contain
-the mentioned edge. Since a cycle contains multiple edges, the suppression
-should be made for the edge that is determined to be an incorrect dependency.
-This also affects the layout of the include dependency graphs (see below): the
-suppressed edge is not considered when determining the dependency order, and is
-shown as invalid in the graph.
-
-Include order sorting {#section_dev_includesorter}
-=====================
-
-The script checks include ordering according to \ref page_devstyle_includes.
-If it is not obvious how the includes should be changed to make the script
-happy, or bulk changes are needed in multiple files, e.g., because of a header
-rename or making a previously public header private, it is possible to run a
-Python script that does the sorting:
-
- docs/doxygen/includesorter.py -S . -B ../build <files>
-
-The script needs to know the location of the source tree (given with `-S`) and
-the build tree (given with `-B`), and sorts the given files. To sort the whole
-source tree, one can also use:
-
- admin/reformat_all.sh includesort -B=../build
-
-For the sorter to work correctly, the build tree should contain up-to-date list
-of installed files and Doxygen XML documentation. The former is created
-automatically when `cmake` is run, and the latter can be built using the
-`doxygen-xml` target.
-
-Note that currently, the sorter script does not change between angle brackets
-and quotes in include statements.
-
-Include dependency graphs
-=========================
-
-The same set of Python scripts can also produce include dependency graphs with
-some additional annotations compared to what, e.g., Doxygen produces for a
-directory dependency graph. Currently, a module-level graph is automatically
-built when the Doxygen documentation is built and embedded in the documentation
-(not in the public API documentation). The graph, together with a legend, is
-on a separate page: \ref page_modulegraph.
-
-The Python script produces the graphs in a format suitable for `dot` (from the
-`graphviz` package) to lay them out. The build system also provides a
-`dep-graphs` target that generates PNG files from the intermediate `dot` files.
-In addition to the module-level graph, a file-level graph is produced for
-each module, showing the include dependencies within that module.
-The file-level graphs can only be viewed as the PNG files, with some
-explanation of the notation below. Currently, these are mostly for eye candy,
-but they can also be used for analyzing problematic dependencies to clean up
-the architecture.
-
-Both the intermediate `.dot` files and the final PNG files are put under
-`docs/doxygen/depgraphs/` in the build tree.
-
-File graphs
------------
-
-The graphs are written to <em>module_name</em>`-deps.dot.png`.
-
-Node colors:
-<dl>
-<dt>light blue</dt>
-<dd>public API (installed) headers</dd>
-<dt>dark blue</dt>
-<dd>library API headers</dd>
-<dt>gray</dt>
-<dd>source files</dd>
-<dt>light green</dt>
-<dd>test files</dd>
-<dt>white</dt>
-<dd>other files</dd>
-</dl>
-
-Each edge signifies an include dependency; there is no additional information
-currently included.
--- /dev/null
+Source tree checker scripts
+===========================
+
+.. highlight:: bash
+
+There is a set of Python scripts, currently under ``docs/doxygen/``, that check
+various aspects of the source tree for consistency. The script is based on
+producing an abstract representation of the source tree from various sources:
+
+* List of files in the source tree (for overall layout of the source tree)
+* List of installed headers (extracted from the generated build system)
+* git attributes (to limit the scope of some checks)
+* Doxygen XML documentation:
+
+ * For tags about public/private nature of documented headers and other
+ constructs
+ * For actual documented constructs, to check them for consistency
+
+* Hard-coded knowledge about the |Gromacs| source tree layout
+
+This representation is then used for various purposes:
+
+* Checking Doxygen documentation elements for common mistakes: missing brief
+ descriptions, mismatches in file and class visibility, etc.
+* Checking for consistent usage and documentation of headers: e.g., a header
+ that is documented as internal to a module should not be used outside that
+ module.
+* Checking for module-level cyclic dependencies
+* Checking for consistent style and order of #include directives
+ (see :doc:`includestyle`)
+* Actually sorting and reformatting #include directives to adhere to the
+ checked style
+* Generating dependency graphs between modules and for files within modules
+
+The checks are run as part of a single ``check-source`` target, but are described
+in separate sections below. In addition to printing the issues to ``stderr``,
+the script also writes them into ``docs/doxygen/check-source.log`` for later
+inspection. Jenkins runs the checks as part of the Documentation job, and the
+build is marked unstable if any issues are found.
+
+For correct functionality, the scripts depend on correct usage of Doxygen
+annotations described in :doc:`doxygen`, in particular the visibility and
+API definitions in file-level comments.
+
+For some false positives from the script, the suppression mechanism described
+below is the easiest way to silence the script, but otherwise the goal would be
+to minimize the number of suppressions.
+
+The scripts require Python 2.7 (other versions may work, but have not been
+tested).
+
+To understand how the scripts work internally, see comments in the Python
+source files under ``docs/doxygen/``.
+
+Checker details
+---------------
+
+The ``check-source`` target currently checks for a few different types of issues.
+These are listed in detail below, mainly related to documentation and include
+dependencies. Note in particular that the include dependency checks are much
+stricter for code in modules/directories that are documented with a
+``\defgroup``: all undocumented code is assumed to be internal to such modules.
+The rationale is that such code has gotten some more attention, and some effort
+should also have been put into defining what is the external interface of the
+module and documenting it.
+
+* For all Doxygen documentation (currently does not apply for members that do
+ not appear in the documentation):
+
+ * If a member has documentation, it should have a brief description.
+ * A note is issued for in-body documentation for functions, since this is
+ ignored by our current settings.
+ * If a class has documentation, it should have public documentation only if
+ it appears in an installed header.
+ * If a class and its containing file has documentation, the class
+ documentation should not be visible if the file documentation is not.
+
+* For all files:
+
+ * Consistent usage of ::
+
+ #include "..." // This should be used for Gromacs headers
+
+ and ::
+
+ #include <...> // This should be used for system and external headers
+
+ * Installed headers must not include non-installed headers.
+ * All source files must include "gmxpre.h" as the first header.
+ * A source/header file should include "config.h" if and only if it uses a
+ macro declared there.
+ * If the file has a git attribute to identify it as a candidate for include
+ sorting, the include sorter described below should not produce any
+ changes (i.e., the file should follow :doc:`includestyle`).
+
+* For documented files:
+
+ * Installed headers should have public documentation, and other files should
+ not.
+ * The API level specified for a file should not be higher than where its
+ documentation is visible. For example, only publicly documented headers
+ should be specified as part of the public API.
+ * If an ``\ingroup module_foo`` exists, it should match the subdirectory
+ that the file is actually part of in the file system.
+ * If a ``\defgroup module_foo`` exists for the subdirectory where the file
+ is, the file should contain ``\ingroup module_foo``.
+ * Files should not include other files whose documentation visibility is
+ lower (if the included file is not documented, the check is skipped).
+
+* For files that are part of documented modules
+ (``\defgroup module_foo`` exists for the subdirectory), or are explicitly
+ documented to be internal or in the library API:
+
+ * Such files should not be included from outside their module if they are
+ undocumented (for documented modules) or are not specified as part of
+ library or public API.
+
+* For all modules:
+
+ * There should not be cyclic include dependencies between modules.
+
+As a side effect, the XML extraction makes Doxygen parse all comments in the
+code, even if they do not appear in the documentation. This can reveal latent
+issues in the comments, like invalid Doxygen syntax. The messages from the XML
+parsing are stored in ``docs/doxygen/doxygen-xml.log`` in the build tree, similar to
+other Doxygen runs.
+
+Suppressing issues
+^^^^^^^^^^^^^^^^^^
+
+The script is not currently perfect (either because of unfinished
+implementation, or because Doxygen bugs or incompleteness of the Doxygen XML
+output), and the current code also contains issues that the script detects, but
+the authors have not fixed. To allow the script to still be used,
+``doxygen/suppressions.txt`` contains a list of issues that are filtered out from
+the report. The syntax is simple::
+
+ <file>: <text>
+
+where ``<file>`` is a path to the file that reports the message, and ``<text>`` is
+the text reported. Both support ``*`` as a wildcard. If ``<file>`` is empty, the
+suppression matches only messages that do not have an associated file.
+``<file>`` is matched against the trailing portion of the file name to make it
+work even though the script reports absolute paths.
+Empty lines and lines starting with ``#`` are ignored.
+
+To add a suppression for an issue, the line that reports the issue can be
+copied into ``suppressions.txt``, and the line number (if any) removed. If the
+issue does not have a file name (or a pseudo-file) associated, a leading ``:``
+must be added. To cover many similar issues, parts of the line can then be
+replaced with wildcards.
+
+A separate suppression mechanism is in place for cyclic dependencies: to
+suppress a cycle between moduleA and moduleB, add a line with format ::
+
+ moduleA -> moduleB
+
+into ``doxygen/cycle-suppressions.txt``. This suppresses all cycles that contain
+the mentioned edge. Since a cycle contains multiple edges, the suppression
+should be made for the edge that is determined to be an incorrect dependency.
+This also affects the layout of the include dependency graphs (see below): the
+suppressed edge is not considered when determining the dependency order, and is
+shown as invalid in the graph.
+
+.. _dev-include-sorter:
+
+Include order sorting
+---------------------
+
+The script checks include ordering according to :doc:`includestyle`.
+If it is not obvious how the includes should be changed to make the script
+happy, or bulk changes are needed in multiple files, e.g., because of a header
+rename or making a previously public header private, it is possible to run a
+Python script that does the sorting::
+
+ docs/doxygen/includesorter.py -S . -B ../build <files>
+
+The script needs to know the location of the source tree (given with ``-S``) and
+the build tree (given with ``-B``), and sorts the given files. To sort the whole
+source tree, one can also use::
+
+ admin/reformat_all.sh includesort -B=../build
+
+For the sorter to work correctly, the build tree should contain up-to-date list
+of installed files and Doxygen XML documentation. The former is created
+automatically when ``cmake`` is run, and the latter can be built using the
+``doxygen-xml`` target.
+
+Note that currently, the sorter script does not change between angle brackets
+and quotes in include statements.
+
+Include dependency graphs
+-------------------------
+
+The same set of Python scripts can also produce include dependency graphs with
+some additional annotations compared to what, e.g., Doxygen produces for a
+directory dependency graph. Currently, a module-level graph is automatically
+built when the Doxygen documentation is built and embedded in the documentation
+(not in the public API documentation). The graph, together with a legend, is
+on a separate page: `Module dependency graph`__
+
+__ doxygen-page-modulegraph_
+
+The Python script produces the graphs in a format suitable for ``dot`` (from the
+``graphviz`` package) to lay them out. The build system also provides a
+``dep-graphs`` target that generates PNG files from the intermediate ``dot`` files.
+In addition to the module-level graph, a file-level graph is produced for
+each module, showing the include dependencies within that module.
+The file-level graphs can only be viewed as the PNG files, with some
+explanation of the notation below. Currently, these are mostly for eye candy,
+but they can also be used for analyzing problematic dependencies to clean up
+the architecture.
+
+Both the intermediate ``.dot`` files and the final PNG files are put under
+``docs/doxygen/depgraphs/`` in the build tree.
+
+File graphs
+^^^^^^^^^^^
+
+The graphs are written to :file:`{module_name}-deps.dot.png`.
+
+Node colors:
+
+light blue
+ public API (installed) headers
+dark blue
+ library API headers
+gray
+ source files
+light green
+ test files
+white
+ other files
+
+Each edge signifies an include dependency; there is no additional information
+currently included.
+
+.. include:: doxygen-links.rst
+++ /dev/null
-Guidelines for \#include directives {#page_devstyle_includes}
-===================================
-
-The following include order is used in \Gromacs. An empty line should appear
-between each group, and headers within each group sorted alphabetically.
-
- 1. Each _source_ file should include `gmxpre.h` first.
- 2. If a _source_ file has a corresponding header, it should be included next.
- If the header is in the same directory as the source, then it is included
- without any path (i.e., relative to the source), otherwise relative to
- `src/`. The latter case is for headers in `legacyheaders/` and for tests.
- 3. If the file depends on defines from `config.h`, that comes next.
- 4. This is followed by standard C/C++ headers, grouped as follows:
-
- 1. Standard C headers (e.g., `<stdio.h>`)
- 2. C++ versions of the above (e.g., `<cstdio>`)
- 3. Standard C++ headers (e.g., `<vector>`)
-
- Preferably, only one of the first two groups is present, but this is not
- enforced.
- 5. This is followed by other system headers: platform-specific headers such as
- `<unistd.h>`, as well as external libraries such as
- `<boost/scoped_ptr.hpp>`.
- 6. \Gromacs-specific libraries from `src/external/`, such as
- `"thread_mpi/threads.h"`.
- 7. \Gromacs-specific headers that are not internal to the including module,
- included with a path relative to `src/`.
- 8. In _test_ files, headers not internal to the module, but specific to
- testing code, are in a separate block at this point, paths relative to
- `src/`.
- 9. Finally, \Gromacs headers that are internal to the including module are
- included using a relative path (but never with a path starting with `../`;
- such headers go into group 7 instead). For test files, this group contains
- headers that are internal to tests for that module.
-
-All \Gromacs headers are included with quotes (`"gromacs/utility/path.h"`),
-other headers with angle brackets (`<stdio.h>`). Headers under `src/external/`
-are generally included with quotes (whenever the include path is relative to
-`src/`, as well as for thread-MPI and TNG), but larger third-party entities are
-included as if they were provided by the system. The latter group currently
-includes boost and gtest/gmock.
-
-If there are any conditionally included headers (typically, only when some
-\#defines from `config.h` are set), these should be included at the end of
-their respective group. Note that the automatic checker/sorter script does not
-act on such headers, nor on comments that are between \#include statements; it
-is up to the author of the code to put the headers in proper order in such
-cases. Trailing comments on the same line as \#include statements are
-preserved and do not affect the checker/sorter.
-
-The guidelines are enforced by an automatic checker script that can also
-sort/reformat include statements to follow the guidelines.
-See \ref page_dev_gmxtree for details.
-
-Enforcing a consistent order and style has a few advantages:
- * It makes it easy at a quick glance to find the dependencies of a file,
- without scanning through a long list of unorganized \#includes.
- * Including the header corresponding to the source file first makes most
- headers included first in some source file, revealing potential problems
- where headers would not compile unless some other header would be included
- first. With this order, the person working on the header is most likely to
- see these problems instead of someone else seeing them later when
- refactoring unrelated code.
- * Consistent usage of paths in \#include directives makes it easy to use
- `grep` to find all uses of a header, as well as all include dependencies
- between two modules.
- * An automatic script can be used to re-establish clean code after
- semi-automatic refactoring like renaming an include file with `sed`, without
- causing other unnecessary changes.
--- /dev/null
+Guidelines for #include directives
+==================================
+
+The following include order is used in |Gromacs|. An empty line should appear
+between each group, and headers within each group sorted alphabetically.
+
+1. Each *source* file should include ``gmxpre.h`` first.
+2. If a *source* file has a corresponding header, it should be included next.
+ If the header is in the same directory as the source, then it is included
+ without any path (i.e., relative to the source), otherwise relative to
+ ``src/``. The latter case is for headers in ``legacyheaders/`` and for tests.
+3. If the file depends on defines from ``config.h``, that comes next.
+4. This is followed by standard C/C++ headers, grouped as follows:
+
+ 1. Standard C headers (e.g., ``<stdio.h>``)
+ 2. C++ versions of the above (e.g., ``<cstdio>``)
+ 3. Standard C++ headers (e.g., ``<vector>``)
+
+ Preferably, only one of the first two groups is present, but this is not
+ enforced.
+5. This is followed by other system headers: platform-specific headers such as
+ ``<unistd.h>``, as well as external libraries such as
+ ``<boost/scoped_ptr.hpp>``.
+6. |Gromacs|-specific libraries from ``src/external/``, such as
+ ``"thread_mpi/threads.h"``.
+7. |Gromacs|-specific headers that are not internal to the including module,
+ included with a path relative to ``src/``.
+8. In *test* files, headers not internal to the module, but specific to
+ testing code, are in a separate block at this point, paths relative to
+ ``src/``.
+9. Finally, |Gromacs| headers that are internal to the including module are
+ included using a relative path (but never with a path starting with ``../``;
+ such headers go into group 7 instead). For test files, this group contains
+ headers that are internal to tests for that module.
+
+All |Gromacs| headers are included with quotes (``"gromacs/utility/path.h"``),
+other headers with angle brackets (``<stdio.h>``). Headers under ``src/external/``
+are generally included with quotes (whenever the include path is relative to
+``src/``, as well as for thread-MPI and TNG), but larger third-party entities are
+included as if they were provided by the system. The latter group currently
+includes boost and gtest/gmock.
+
+If there are any conditionally included headers (typically, only when some
+#defines from ``config.h`` are set), these should be included at the end of
+their respective group. Note that the automatic checker/sorter script does not
+act on such headers, nor on comments that are between #include statements; it
+is up to the author of the code to put the headers in proper order in such
+cases. Trailing comments on the same line as #include statements are
+preserved and do not affect the checker/sorter.
+
+The guidelines are enforced by an automatic checker script that can also
+sort/reformat include statements to follow the guidelines.
+See :doc:`gmxtree` for details.
+
+Enforcing a consistent order and style has a few advantages:
+
+* It makes it easy at a quick glance to find the dependencies of a file,
+ without scanning through a long list of unorganized #includes.
+* Including the header corresponding to the source file first makes most
+ headers included first in some source file, revealing potential problems
+ where headers would not compile unless some other header would be included
+ first. With this order, the person working on the header is most likely to
+ see these problems instead of someone else seeing them later when
+ refactoring unrelated code.
+* Consistent usage of paths in #include directives makes it easy to use
+ ``grep`` to find all uses of a header, as well as all include dependencies
+ between two modules.
+* An automatic script can be used to re-establish clean code after
+ semi-automatic refactoring like renaming an include file with ``sed``, without
+ causing other unnecessary changes.
--- /dev/null
+***************
+Developer guide
+***************
+
+This set of pages contains guidelines, instructions, and explanations related
+to |Gromacs| development. The actual code is documented in Doxygen
+documentation linked from the front page of the documentation.
+
+The focus is (at least for now) on things that are tightly tied to the code
+itself, such as helper scripts that reside in the source repository, and may
+require the documentation to be updated in sync. Wiki pages at
+http://www.gromacs.org/Developer_Zone contain additional information (much of
+it outdated, though), and can be linked from relevant locations in this guide.
+
+The guide is currently split into two main parts:
+
+ * Generic guidelines to follow when developing |Gromacs|.
+ For some of the guidelines, scripts exist (see below) to automatically
+ reformat the code and/or enforce the guidelines for each commit.
+ * Instructions on what tools are used, and how to use them.
+
+.. toctree::
+ :maxdepth: 2
+
+ style
+ tools
+++ /dev/null
-Naming conventions {#page_devstyle_naming}
-==================
-
-The conventions here should be applied to all new code, and with common sense
-when modifying existing code. For example, renaming a widely used, existing
-function to follow these conventions may not be justified unless the whole code
-is getting a rework.
-
-Currently, this only documents the present state of the code: no particular
-attempt has been made to consolidate the naming.
-
-Files
-=====
-
- * Avoid having multiple files with the same name in different places within
- the same library. In addition to making things harder to find, C++ source
- files with the same name can cause obscure problems with some compilers.
- Currently, unit tests are an exception to the rule (there is only one
- particular compiler that had problems with this, and a workaround is
- possible if/when that starts to affect more than a few of the test files).
- * For C++ files, prefer naming the file the same as the (main) class it
- contains. Currently all file names are all-lowercase, even though class
- names contain capital letters.
- It is OK to use commonly known abbreviations, and/or omit the name of the
- containing directory if that would cause unnecessary repetition (e.g., as a
- common prefix to every file name in the directory) and the remaining part of
- the name is unique enough.
-
-TODO: Copy/move relevant content from \ref page_codelayout here, and add
-details.
-
-TODO: Consider usage of underscores vs dashes in file names.
-
-Common guidelines for C and C++ code
-====================================
-
- * Preprocessor macros should be all upper-case. Do not use leading
- underscores, as all such names are reserved according to the C/C++ standard.
- * Name include guards like `GMX_DIRNAME_HEADERNAME_H`.
- * Boolean variables are always named with a `b` prefix, followed by a
- CamelCase name.
- * Enum values are named with an `e` prefix. For enum types exposed widely in
- the codebase, this is followed typically by a part that makes the enum
- values not conflict with other enums in the same scope. In C code, this is
- typically an all-lowercase acronym (e.g., `epbcNONE`); in C++, the same
- approach may be used, or the name of the enum type is used (e.g.,
- `eHelpOutputFormat_Console`).
- * Avoid abbreviations that are not obvious to a general reader.
- * If you use acronyms (e.g., PME, DD) in names, follow the Microsoft policy on
- casing: two letters is uppercase (DD), three or more is lowercase (Pme).
- If the first letter would be lowercase in the context where it is used
- (e.g., at the beginning of a function name, or anywhere in a C function
- name), it is clearest to use all-lowercase acronym.
-
-C code
-======
-
- * All function and variable names are lowercase, with underscores as word
- separators where needed for clarity.
- * All functions that are part of the public API should start with `gmx_`.
- Preferably, other functions should as well.
- Some parts of the code use a `_gmx_` prefix for internal functions, but
- strictly speaking, these are reserved names, so, e.g., a trailing underscore
- would be better.
-
-C++ code
-========
-
- * Use CamelCase for all names. Start types (such as classes, structs, and
- typedefs) with a capital letter, other names (functions, variables) with a
- lowercase letter.
- You may use an all-lowercase name with underscores if your class closely
- resembles an external construct (e.g., a standard library construct) named
- that way.
- * C++ interfaces are named with a `Interface` suffix, and abstract base
- classes with an `Abstract` prefix.
- * Member variables are named with a trailing underscore.
- * Accessors for a variable `foo_` are named `foo()` and `setFoo()`.
- * Global variables are named with a `g_` prefix.
- * Static class variables are named with a `s_` prefix.
- * Global constants are often named with a `c_` prefix.
- * If the main responsibility of a file is to implement a particular class,
- then the name of the file should match that class, except for possible
- abbreviations to avoid repetition in file names (e.g., if all classes within
- a module start with the module name, omitting or abbreviating the module
- name is OK). Currently, all source file names are lowercase, but this
- casing difference should be the only difference.
-
-The rationale for the trailing underscore and the global/static prefixes is
-that it is immediately clear whether a variable referenced in a method is local
-to the function or has wider scope, improving the readability of the code.
-
-Unit tests
-==========
-
- * Test fixtures (the first parameter to `TEST`/`TEST_F`) are named with a
- `Test` suffix.
- * Classes meant as base classes for test fixtures (or as names to be typedefed
- to be fixtures) are named with a `TestBase` of `Fixture` suffix.
- * The CTest test is named with CamelCase, ending with `Tests` (e.g.,
- `OptionsUnitTests`).
- * The test binary is named with the name of the module and a `-test` suffix.
--- /dev/null
+Naming conventions
+==================
+
+The conventions here should be applied to all new code, and with common sense
+when modifying existing code. For example, renaming a widely used, existing
+function to follow these conventions may not be justified unless the whole code
+is getting a rework.
+
+Currently, this only documents the present state of the code: no particular
+attempt has been made to consolidate the naming.
+
+Files
+-----
+
+* Avoid having multiple files with the same name in different places within
+ the same library. In addition to making things harder to find, C++ source
+ files with the same name can cause obscure problems with some compilers.
+ Currently, unit tests are an exception to the rule (there is only one
+ particular compiler that had problems with this, and a workaround is
+ possible if/when that starts to affect more than a few of the test files).
+* For C++ files, prefer naming the file the same as the (main) class it
+ contains. Currently all file names are all-lowercase, even though class
+ names contain capital letters.
+ It is OK to use commonly known abbreviations, and/or omit the name of the
+ containing directory if that would cause unnecessary repetition (e.g., as a
+ common prefix to every file name in the directory) and the remaining part of
+ the name is unique enough.
+
+.. TODO: Copy/move relevant content from Doxygen page_codelayout here, and add
+ details.
+
+.. TODO: Consider usage of underscores vs dashes in file names.
+
+Common guidelines for C and C++ code
+------------------------------------
+
+* Preprocessor macros should be all upper-case. Do not use leading
+ underscores, as all such names are reserved according to the C/C++ standard.
+* Name include guards like ``GMX_DIRNAME_HEADERNAME_H``.
+* Boolean variables are always named with a ``b`` prefix, followed by a
+ CamelCase name.
+* Enum values are named with an ``e`` prefix. For enum types exposed widely in
+ the codebase, this is followed typically by a part that makes the enum
+ values not conflict with other enums in the same scope. In C code, this is
+ typically an all-lowercase acronym (e.g., ``epbcNONE``); in C++, the same
+ approach may be used, or the name of the enum type is used (e.g.,
+ ``eHelpOutputFormat_Console``).
+* Avoid abbreviations that are not obvious to a general reader.
+* If you use acronyms (e.g., PME, DD) in names, follow the Microsoft policy on
+ casing: two letters is uppercase (DD), three or more is lowercase (Pme).
+ If the first letter would be lowercase in the context where it is used
+ (e.g., at the beginning of a function name, or anywhere in a C function
+ name), it is clearest to use all-lowercase acronym.
+
+C code
+------
+
+* All function and variable names are lowercase, with underscores as word
+ separators where needed for clarity.
+* All functions that are part of the public API should start with ``gmx_``.
+ Preferably, other functions should as well.
+ Some parts of the code use a ``_gmx_`` prefix for internal functions, but
+ strictly speaking, these are reserved names, so, e.g., a trailing underscore
+ would be better.
+
+C++ code
+--------
+
+* Use CamelCase for all names. Start types (such as classes, structs, and
+ typedefs) with a capital letter, other names (functions, variables) with a
+ lowercase letter.
+ You may use an all-lowercase name with underscores if your class closely
+ resembles an external construct (e.g., a standard library construct) named
+ that way.
+* C++ interfaces are named with a ``Interface`` suffix, and abstract base
+ classes with an ``Abstract`` prefix.
+* Member variables are named with a trailing underscore.
+* Accessors for a variable ``foo_`` are named ``foo()`` and ``setFoo()``.
+* Global variables are named with a ``g_`` prefix.
+* Static class variables are named with a ``s_`` prefix.
+* Global constants are often named with a ``c_`` prefix.
+* If the main responsibility of a file is to implement a particular class,
+ then the name of the file should match that class, except for possible
+ abbreviations to avoid repetition in file names (e.g., if all classes within
+ a module start with the module name, omitting or abbreviating the module
+ name is OK). Currently, all source file names are lowercase, but this
+ casing difference should be the only difference.
+
+The rationale for the trailing underscore and the global/static prefixes is
+that it is immediately clear whether a variable referenced in a method is local
+to the function or has wider scope, improving the readability of the code.
+
+Unit tests
+----------
+
+* Test fixtures (the first parameter to ``TEST``/``TEST_F``) are named with a
+ ``Test`` suffix.
+* Classes meant as base classes for test fixtures (or as names to be typedefed
+ to be fixtures) are named with a ``TestBase`` or ``Fixture`` suffix.
+* The CTest test is named with CamelCase, ending with ``Tests`` (e.g.,
+ ``OptionsUnitTests``).
+* The test binary is named with the name of the module and a ``-test`` suffix.
+++ /dev/null
-Style guidelines {#page_devstyle}
-================
-
- - \subpage page_devstyle_formatting <br/>
- Guidelines for indentation and other code formatting.
-
- - \subpage page_devstyle_includes <br/>
- Guidelines for \#include style (ordering, paths to use, etc.).
-
- - \subpage page_devstyle_naming <br/>
- Naming conventions for files and various code constructs.
-
- - [Doxygen guidelines](\ref section_doxygen_guidelines) <br/>
- Guidelines for using Doxygen to document the source code are currently in a
- section on the page on general Doxygen usage.
-
-TODO: Add more guidelines
--- /dev/null
+Style guidelines
+================
+
+.. toctree::
+ :maxdepth: 2
+
+ formatting
+ includestyle
+ naming
+
+:doc:`formatting`
+ Guidelines for indentation and other code formatting.
+:doc:`includestyle`
+ Guidelines for #include style (ordering, paths to use, etc.).
+:doc:`naming`
+ Naming conventions for files and various code constructs.
+:ref:`dev-doxygen-guidelines`
+ Guidelines for using Doxygen to document the source code are currently in a
+ section on the page on general Doxygen usage.
+
+.. TODO: Add more guidelines
+++ /dev/null
-Development-time tools {#page_devtools}
-======================
-
-TODO: Add details for most of the tools, either in the form of links to wiki,
-or to a separate page that explains more details.
-
-Change management
-=================
-
-<dl>
-
-<dt>git</dt>
-<dd>\Gromacs uses git as the version control system.
-Instructions for setting up git for \Gromacs, as well as tips and tricks for
-its use, can be found on the wiki:
-[Git Tips & Tricks](http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks) <br/>
-Other basic tutorial material for `git` can be found on the web.</dd>
-
-<dt>Gerrit</dt>
-<dd>All code changes go through a code review system at
-<http://gerrit.gromacs.org>.</dd>
-
-<dt>Jenkins</dt>
-<dd>All changes pushed to Gerrit are automatically compiled and otherwise
-checked on various platforms using a continuous integration system at
-<http://jenkins.gromacs.org>.</dd>
-
-<dt>Redmine</dt>
-<dd>Bugs and issues, as well as some random features and discussions,
-are tracked at <http://redmine.gromacs.org>.</dd>
-
-</dl>
-
-Build system
-============
-
-TODO: details, ASAN, others?
-
-<dl>
-
-<dt>CMake</dt>
-<dd></dd>
-
-<dt>packaging for distribution (CPack)</dt>
-<dd></dd>
-
-<dt>unit testing (CTest)</dt>
-<dd>\Gromacs uses a unit testing framework based on Google C++ Testing
-Framework (gtest) and CTest. All unit tests are automatically run on Jenkins
-for each commit.
-Details can be found on a separate page: \subpage page_unittesting.</dd>
-
-<dt>regression tests</dt>
-<dd></dd>
-
-<dt>cppcheck</dt>
-<dd>cppcheck (<http://cppcheck.sourceforge.net>) is used for static code
-analysis, and is run automatically on Jenkins for each commit. Different rules
-are used for C and C++ code (with stricter checking for C++ code, as that is
-newer). The build system provides a `cppcheck` target (produced from
-`tests/CppCheck.cmake`) to run the tool. This target is used also by Jenkins.
-</dd>
-
-<dt>clang static analyzer</dt>
-<dd></dd>
-
-</dl>
-
-Code formatting and style {#section_dev_formattingtools}
-=========================
-
-The tools and scripts listed below are used to automatically check/apply
-formatting that follows \Gromacs style guidelines described on a separate page:
-\ref page_devstyle.
-
-<dl>
-
-<dt>uncrustify</dt>
-<dd>Uncrustify (<http://uncrustify.sourceforge.net>) is used for automatic
-indentation and other formatting of the source code to follow
-\ref page_devstyle_formatting. All code must remain invariant under uncrustify
-with the config at `admin/uncrustify.cfg`. A patched version of uncrustify is
-used. See \ref page_dev_uncrustify for details.</dd>
-
-<dt>`admin/copyright.py`</dt>
-<dd>This Python script adds and formats copyright headers in source files.
-`uncrustify.sh` (see below) uses the script to check/update copyright years on
-changed files automatically.</dd>
-
-<dt>`admin/uncrustify.sh`</dt>
-<dd>This `bash` script runs uncrustify and `copyright.py` for all
-files that have local changes and checks that they conform to the prescribed
-style. Optionally, the script can also apply changes to make the files
-conform.
-This script is automatically run by Jenkins to ensure that all commits adhere
-to \ref page_devstyle_formatting. If the uncrustify job does not succeed, it
-means that this script has something to complain.
-See \ref page_dev_uncrustify for details.</dd>
-
-<dt>`admin/git-pre-commit`</dt>
-<dd>This sample git pre-commit hook can be used if one wants to apply
-`uncrustify.sh` automatically before every commit to check for formatting
-issues. See \ref page_dev_uncrustify for details.</dd>
-
-<dt>`docs/doxygen/includesorter.py`</dt>
-<dd>This Python script sorts and reformats \#include directives according to
-the guidelines at \ref page_devstyle_includes. Details are documented on a
-separate page (with the whole suite of Python scripts used for source code
-checks): \ref section_dev_includesorter.</dd>
-
-<dt>include directive checker</dt>
-<dd>In its present form, the above include sorter script cannot be conveniently
-applied in `uncrustify.sh`. To check for issues, it is instead integrated into
-a `check-source` build target. When this target is built, it also checks for
-include formatting issues. Internally, it uses the sorter script. This check
-is run in Jenkins as part of the Documentation job.
-Details for the checking mechanism are on a separate page (common for several
-checkers): \subpage page_dev_gmxtree.</dd>
-
-<dt>`admin/reformat_all.sh`</dt>
-<dd>This `bash` script runs uncrustify/`copyright.py`/include sorter
-on all relevant files in the source tree (or in a particular directory).
-The script can also produce the list of files where these scripts are applied,
-for use with other scripts. See \ref page_dev_uncrustify for details.</dd>
-
-<dt>git attributes</dt>
-<dd>git attributes (specified in `.gitattributes` files) are used to annotate
-which files are subject to automatic formatting checks (and for automatic
-reformatting by the above scripts). See `man gitattributes` for an overview of
-the mechanism. We use the `filter` attribute to specify the type of automatic
-checking/formatting to apply. Custom attributes are used for specifying some
-build system dependencies for easier processing in CMake.</dd>
-
-<dt>include-what-you-use</dt>
-<dd></dd>
-
-</dl>
-
-Documentation generation
-========================
-
-Building the \Gromacs documentation
------------------------------------
-
-TODO: Move this onto a separate page
-
-For now, there are multiple components, formats and tools for the
-\Gromacs documentation, which is aimed primarily at version-specific
-deployment of the complete documentation on the website.
-
-This is quite complex, because the dependencies for building the
-documentation must not get in the way of building the code
-(particularly when cross-compiling), and yet the code must build and
-run in order for some documentation to be generated. Also, man page
-documentation (and command-line completions) must be built from the
-wrapper binary, in order to be bundled into the tarball.
-
-The outputs of interest to most developers are generally produced in the
-<tt>docs/html/</tt> subdirectory of the build tree.
-
-You need to enable at least some of the following CMake options:
-<dl>
-<dt><tt>GMX_BUILD_MANUAL</tt></dt>
-<dd>Option needed for trying to build the PDF reference manual
-(requires LaTeX and ImageMagick)</dd>
-<dt><tt>GMX_BUILD_HELP</tt></dt>
-<dd>Option that controls 1) whether shell completions are built automatically,
-and 2) whether built man pages are installed if available (the user still needs
-to build the `man` target manually before installing)</dd>
-<dt><tt>GMX_BUILD_WEBPAGE</tt></dt>
-<dd>Option needed for compiling all the documentation into the webpage</dd>
-</dl>
-Some documentation cannot be built if the CMake option
-<tt>GMX_BUILD_MDRUN_ONLY</tt> is enabled, or when cross-compiling, as it
-requires executing the `gmx` binary.
-
-The following make targets are the most useful:
-<dl>
-<dt><tt>manual</tt></dt>
-<dd>Builds the PDF reference manual</dd>
-<dt><tt>man</tt></dt>
-<dd>Makes man pages from the wrapper binary with Sphinx</dd>
-<dt><tt>doxygen-all</tt></dt>
-<dd>Makes the code documentation with Doxygen</dd>
-<dt><tt>install-guide</tt></dt>
-<dd>Makes the INSTALL file for the tarball with Sphinx</dd>
-<dt><tt>webpage-sphinx</tt></dt>
-<dd>Makes all the components of the GROMACS webpage that require Sphinx,
-including install guide and user guide.</dd>
-<dt><tt>webpage</tt></dt>
-<dd>Makes the complete GROMACS webpage, requires everything. When complete,
-you can browse <tt>docs/html/index.html</tt> to find everything.
-
-If built from a release tarball, the <tt>SOURCE_MD5SUM</tt>,
-<tt>SOURCE_TARBALL</tt>, <tt>REGRESSIONTESTS_MD5SUM</tt>, and
-<tt>REGRESSIONTESTS_TARBALL</tt> CMake variables can be set to pass in
-the md5sum values and names of those tarballs, for embedding into the
-final deployment to the \Gromacs website.</dd>
-</dl>
-
-The following tools are used in building parts of the documentation.
-
-<dl>
-<dt>Doxygen</dt>
-<dd>Doxygen (<http://www.doxygen.org>) is used to extract documentation from
-source code comments. Also this developer manual and some other overview
-content is laid out by Doxygen from Markdown source files. Currently, version
-1.8.5 is required for a warning-free build. Thorough explanation of the
-Doxygen setup and instructions for documenting the source code can be found on
-a separate page: \subpage page_doxygen.</dd>
-
-<dt>graphviz (dot)</dt>
-<dd>The Doxygen documentation uses `dot` from graphviz
-(<http://www.graphviz.org>) for building some graphs. The tool is not
-mandatory, but the Doxygen build will produce warnings if it is not
-available, and the graphs are omitted from the documentation.</dd>
-
-<dt>mscgen</dt>
-<dd>The Doxygen documentation uses `mscgen`
-(<http://www.mcternan.me.uk/mscgen/>) for building some graphs. As with `dot`,
-the tool is not mandatory, but not having it available will result in warnings
-and missing graphs.</dd>
-
-<dt>Doxygen issue checker</dt>
-<dd>Doxygen produces warnings about some incorrect uses and wrong
-documentation, but there are many common mistakes that it does not detect.
-\Gromacs uses an additional, custom Python script to check for such issues.
-This is most easily invoked through a `check-source` target in the build system.
-The script also checks that documentation for a header matches its use in the
-source code (e.g., that a header documented as internal to a module is not
-actually used from outside the module). These checks are run in Jenkins as
-part of the Documentation job. Details for the custom checker are on a
-separate page (common for several checkers): \subpage page_dev_gmxtree.</dd>
-
-<dt>module dependency graphs</dt>
-<dd>\Gromacs uses a custom Python script to generate an annotated dependency
-graph for the code, showing \#include dependencies between modules.
-The generated graph is embedded into the Doxygen documentation:
-\ref page_modulegraph.
-This script shares most of its implementation with the custom checkers, and is
-documented on the same page: \subpage page_dev_gmxtree.</dd>
-
-<dt>Sphinx</dt>
-<dd>Sphinx (<http://sphinx-doc.org/>; at least version 1.2.3) is used
-for building some parts of the documentation from reStructuredText
-source files.</dd>
-
-<dt>latex</dt>
-<dd>Also requires ImageMagick for converting graphics file formats</dd>
-
-<dt>linkchecker</dt>
-<dd></dd>
-
-<dt>documentation exported from source files</dt>
-<dd>For man pages, HTML documentation of command-line options for executables,
-and for shell completions, the `gmx` binary has explicit C++ code to export
-the information required. The build system provides targets that then invoke
-the built `gmx` binary to produce these documentation items. The generated
-items are packaged into source tarballs so that this is not necessary when
-building from a source distribution (since in general, it will not work in
-cross-compilation scenarios). To build and install these from a git
-distribution, explicit action is required.
-See \ref page_wrapperbinary for some additional details.</dd>
-
-</dl>
--- /dev/null
+Development-time tools
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ doxygen
+ gmxtree
+ uncrustify
+
+.. TODO: Add details for most of the tools, either in the form of links to wiki,
+ or to a separate page that explains more details.
+
+Change management
+-----------------
+
+git
+ |Gromacs| uses git as the version control system.
+ Instructions for setting up git for |Gromacs|, as well as tips and tricks for
+ its use, can be found on the wiki: `Git Tips & Tricks`_
+
+ Other basic tutorial material for ``git`` can be found on the web.
+
+Gerrit
+ All code changes go through a code review system at
+ http://gerrit.gromacs.org.
+
+Jenkins
+ All changes pushed to Gerrit are automatically compiled and otherwise
+ checked on various platforms using a continuous integration system at
+ http://jenkins.gromacs.org.
+
+Redmine
+ Bugs and issues, as well as some random features and discussions,
+ are tracked at http://redmine.gromacs.org.
+
+.. _Git Tips & Tricks: http://www.gromacs.org/index.php?title=Developer_Zone/Git/Git_Tips_%26_Tricks
+
+Build system
+------------
+
+.. TODO: details, ASAN, others?
+
+CMake
+ Main tool used in the build system.
+
+packaging for distribution (CPack)
+
+unit testing (CTest)
+ |Gromacs| uses a unit testing framework based on Google C++ Testing
+ Framework (gtest) and CTest. All unit tests are automatically run on Jenkins
+ for each commit.
+ Details can be found on a separate page on
+ `unit testing in the Doxygen documentation`__
+
+__ doxygen-page-unittesting_
+
+regression tests
+
+cppcheck
+ `cppcheck <http://cppcheck.sourceforge.net>`_ is used for static code
+ analysis, and is run automatically on Jenkins for each commit. Different rules
+ are used for C and C++ code (with stricter checking for C++ code, as that is
+ newer). The build system provides a ``cppcheck`` target (produced from
+ ``tests/CppCheck.cmake``) to run the tool. This target is used also by Jenkins.
+
+clang static analyzer
+
+.. _dev-formatting-tools:
+
+Code formatting and style
+-------------------------
+
+The tools and scripts listed below are used to automatically check/apply
+formatting that follows |Gromacs| style guidelines described on a separate page:
+:doc:`style`.
+
+uncrustify
+ `uncrustify <http://uncrustify.sourceforge.net>`_ is used for automatic
+ indentation and other formatting of the source code to follow
+ :doc:`formatting`. All code must remain invariant under uncrustify
+ with the config at ``admin/uncrustify.cfg``. A patched version of uncrustify is
+ used. See :doc:`uncrustify` for details.
+
+``admin/copyright.py``
+ This Python script adds and formats copyright headers in source files.
+ ``uncrustify.sh`` (see below) uses the script to check/update copyright years on
+ changed files automatically.
+
+``admin/uncrustify.sh``
+ This ``bash`` script runs uncrustify and ``copyright.py`` for all
+ files that have local changes and checks that they conform to the prescribed
+ style. Optionally, the script can also apply changes to make the files
+ conform.
+ This script is automatically run by Jenkins to ensure that all commits adhere
+ to :doc:`formatting`. If the uncrustify job does not succeed, it
+ means that this script has something to complain.
+ See :doc:`uncrustify` for details.
+
+``admin/git-pre-commit``
+ This sample git pre-commit hook can be used if one wants to apply
+ ``uncrustify.sh`` automatically before every commit to check for formatting
+ issues. See :doc:`uncrustify` for details.
+
+``docs/doxygen/includesorter.py``
+ This Python script sorts and reformats #include directives according to
+ the guidelines at :doc:`includestyle`. Details are documented on a
+ separate page (with the whole suite of Python scripts used for source code
+ checks): :ref:`dev-include-sorter`.
+
+include directive checker
+ In its present form, the above include sorter script cannot be conveniently
+ applied in ``uncrustify.sh``. To check for issues, it is instead integrated into
+ a ``check-source`` build target. When this target is built, it also checks for
+ include formatting issues. Internally, it uses the sorter script. This check
+ is run in Jenkins as part of the Documentation job.
+ Details for the checking mechanism are on a separate page (common for several
+ checkers): :doc:`gmxtree`.
+
+``admin/reformat_all.sh``
+ This ``bash`` script runs uncrustify/``copyright.py``/include sorter
+ on all relevant files in the source tree (or in a particular directory).
+ The script can also produce the list of files where these scripts are applied,
+ for use with other scripts. See :doc:`uncrustify` for details.
+
+git attributes
+ git attributes (specified in ``.gitattributes`` files) are used to annotate
+ which files are subject to automatic formatting checks (and for automatic
+ reformatting by the above scripts). See ``man gitattributes`` for an overview of
+ the mechanism. We use the ``filter`` attribute to specify the type of automatic
+ checking/formatting to apply. Custom attributes are used for specifying some
+ build system dependencies for easier processing in CMake.
+
+include-what-you-use
+
+Documentation generation
+------------------------
+
+Building the |Gromacs| documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. TODO: Move this onto a separate page
+
+For now, there are multiple components, formats and tools for the
+|Gromacs| documentation, which is aimed primarily at version-specific
+deployment of the complete documentation on the website.
+
+This is quite complex, because the dependencies for building the
+documentation must not get in the way of building the code
+(particularly when cross-compiling), and yet the code must build and
+run in order for some documentation to be generated. Also, man page
+documentation (and command-line completions) must be built from the
+wrapper binary, in order to be bundled into the tarball.
+
+The outputs of interest to most developers are generally produced in the
+``docs/html/`` subdirectory of the build tree.
+
+You need to enable at least some of the following CMake options:
+
+``GMX_BUILD_MANUAL``
+ Option needed for trying to build the PDF reference manual
+ (requires LaTeX and ImageMagick)
+``GMX_BUILD_HELP``
+ Option that controls 1) whether shell completions are built automatically,
+ and 2) whether built man pages are installed if available (the user still needs
+ to build the ``man`` target manually before installing)
+``GMX_BUILD_WEBPAGE``
+ Option needed for compiling all the documentation into the webpage
+
+Some documentation cannot be built if the CMake option
+``GMX_BUILD_MDRUN_ONLY`` is enabled, or when cross-compiling, as it
+requires executing the ``gmx`` binary.
+
+The following make targets are the most useful:
+
+``manual``
+ Builds the PDF reference manual
+``man``
+ Makes man pages from the wrapper binary with Sphinx
+``doxygen-all``
+ Makes the code documentation with Doxygen
+``install-guide``
+ Makes the INSTALL file for the tarball with Sphinx
+``webpage-sphinx``
+ Makes all the components of the GROMACS webpage that require Sphinx,
+ including install guide and user guide.
+``webpage``
+ Makes the complete GROMACS webpage, requires everything. When complete,
+ you can browse ``docs/html/index.html`` to find everything.
+
+ If built from a release tarball, the ``SOURCE_MD5SUM``,
+ ``SOURCE_TARBALL``, ``REGRESSIONTESTS_MD5SUM``, and
+ ``REGRESSIONTESTS_TARBALL`` CMake variables can be set to pass in
+ the md5sum values and names of those tarballs, for embedding into the
+ final deployment to the |Gromacs| website.
+
+The following tools are used in building parts of the documentation.
+
+Doxygen
+ `Doxygen <http://www.doxygen.org>`_ is used to extract documentation from
+ source code comments. Also some other overview
+ content is laid out by Doxygen from Markdown source files. Currently, version
+ 1.8.5 is required for a warning-free build. Thorough explanation of the
+ Doxygen setup and instructions for documenting the source code can be found on
+ a separate page: :doc:`doxygen`.
+
+graphviz (dot)
+ The Doxygen documentation uses ``dot`` from `graphviz
+ <http://www.graphviz.org>`_ for building some graphs. The tool is not
+ mandatory, but the Doxygen build will produce warnings if it is not
+ available, and the graphs are omitted from the documentation.
+
+mscgen
+ The Doxygen documentation uses `mscgen
+ <http://www.mcternan.me.uk/mscgen/>`_ for building some graphs. As with ``dot``,
+ the tool is not mandatory, but not having it available will result in warnings
+ and missing graphs.
+
+Doxygen issue checker
+ Doxygen produces warnings about some incorrect uses and wrong
+ documentation, but there are many common mistakes that it does not detect.
+ |Gromacs| uses an additional, custom Python script to check for such issues.
+ This is most easily invoked through a ``check-source`` target in the build system.
+ The script also checks that documentation for a header matches its use in the
+ source code (e.g., that a header documented as internal to a module is not
+ actually used from outside the module). These checks are run in Jenkins as
+ part of the Documentation job. Details for the custom checker are on a
+ separate page (common for several checkers): :doc:`gmxtree`.
+
+module dependency graphs
+ |Gromacs| uses a custom Python script to generate an annotated dependency
+ graph for the code, showing #include dependencies between modules.
+ The generated graph is embedded into the Doxygen documentation:
+ `Module dependency graph`__
+ This script shares most of its implementation with the custom checkers, and is
+ documented on the same page: :doc:`gmxtree`.
+
+__ doxygen-page-modulegraph_
+
+Sphinx
+ `Sphinx <http://sphinx-doc.org/>`_; at least version 1.2.3) is used
+ for building some parts of the documentation from reStructuredText
+ source files.
+
+LaTeX
+ Also requires ImageMagick for converting graphics file formats.
+
+linkchecker
+
+documentation exported from source files
+ For man pages, HTML documentation of command-line options for executables,
+ and for shell completions, the ``gmx`` binary has explicit C++ code to export
+ the information required. The build system provides targets that then invoke
+ the built ``gmx`` binary to produce these documentation items. The generated
+ items are packaged into source tarballs so that this is not necessary when
+ building from a source distribution (since in general, it will not work in
+ cross-compilation scenarios). To build and install these from a git
+ distribution, explicit action is required.
+ See `Doxygen documentation on the wrapper binary`__
+ for some additional details.
+
+__ doxygen-page-wrapperbinary_
+
+.. include:: doxygen-links.rst
+++ /dev/null
-Automatic source code formatting {#page_dev_uncrustify}
-================================
-
-The source code can be automatically formatted using uncrustify, an automatic
-source code formatting tool, to follow the guidelines in
-\ref page_devstyle_formatting.
-Additionally, Python scripts are used for a few other automatic
-formatting/checking tasks. The overview tools page contains a list of these
-tools: \ref section_dev_formattingtools.
-This page provides more details for uncrustify and copyright scripts.
-
-Jenkins uses these same scripts (in particular, `uncrustify.sh` and the
-`check-source` target) to enforce that the code stays invariant under such
-formatting.
-
-Setting up uncrustify
-=====================
-
-A patched version of uncrustify is used for \Gromacs. To set this up, you need
-to do these (once):
- 1. Change to a directory under which you want to build uncrustify and run:
-
- git clone -b gromacs git://github.com/rolandschulz/uncrustify.git
- cd uncrustify
- ./configure
- make
-
- 2. Copy the binary `src/uncrustify` into a directory of your choice
- (`/path/to/uncrustify` below).
-
-Alternatively, if you are running Linux, you can try whether the binary from
-<http://redmine.gromacs.org/issues/845> works for you.
-
-In order to use the binary for `uncrustify.sh` and for the pre-commit hook, you
-also need to run this in each of your \Gromacs repositories:
-
- git config hooks.uncrustifypath /path/to/uncrustify
-
-Alternatively, if you just want to use `uncrustify.sh`, you can set the
-UNCRUSTIFY environment variable to `/path/to/uncrustify`.
-
-Using the pre-commit hook or git filters needs additional setup; see the
-respective sections below.
-
-What is automatically formatted?
-================================
-
-To identify which files are subject to automatic formatting, the scripts use
-git filters, specified in `.gitattributes` files. Only files that have the
-attribute `filter` set to one of the below values are processed:
- - `filter=uncrustify`: uncrustify is run, copyright headers are checked, and
- include order is enforced
- - `filter=uncrustify_only`: only uncrustify is run
- - `filter=includesort`: include order is enforced and copyright headers are
- checked
- - `filter=copyright`: only copyright headers are checked
-Other files are ignored by `uncrustify.sh` and `reformat_all.sh` scripts (see
-below).
-
-
-Scripts
-=======
-
-`copyright.py`
---------------
-
-This script provides low-level functionality to check and update copyright
-headers in C/C++ source files, as well as in several other types of files like
-CMake and Python scripts.
-
-This file is also used as a loadable Python module for kernel generators, and
-provides the functionality to generate conformant copyright headers for such
-scripts.
-
-The script is similar to uncrustify in that there is rarely need to run it
-directly, but instead the bash scripts below use it internally. You can run
-the script with `--help` option if you want to see what all options it provides
-if you need to do some maintenance on the copyright headers themselves.
-
-`uncrustify.sh`
----------------
-
-This script runs uncrustify and `copyright.py` on modified files and
-reports/applies the results.
-By default, the current HEAD commit is compared to the work tree,
-and files that
-
- 1. are different between these two trees and
- 2. change under uncrustify and/or have outdated copyright header
-
-are reported. This behavior can be changed by
-
- 1. Specifying an `--rev=REV` argument, which uses `REV` instead of HEAD as
- the base of the comparison. A typical use case is to specify `--rev=HEAD^`
- to check the HEAD commit.
- 2. Specifying an action:
- - `check-*`: reports the files that uncrustify changes
- - `diff-*`: prints the actual diff of what would change
- - `update-*`: applies the changes to the repository
- - `*-workdir`: operates on the working directory (files on disk)
- - `*-index`: operates on the index of the repository
- For convenience, if you omit the workdir/index suffix, workdir is assumed
- (i.e., `diff` equals `diff-workdir`).
- 3. Specifying `--uncrustify=off`, which does not run uncrustify.
- 4. Specifying `--copyright=<mode>`, which alters the level of copyright
- checking is done:
- - `off`: does not check copyright headers at all
- - `year`: only update copyright year in new-format copyright headers
- - `add`: in addition to 'year', add copyright headers to files that
- do not have any
- - `update`: in addition to 'year' and 'add', also update new-format
- copyright headers if they are broken or outdated.
- - `replace`: replace any copyright header with a new-format copyright
- header
- - `full`: do all of the above
-
-By default, `update-*` refuses to update dirty files (i.e., that differ
-between the disk and the index) to make it easy to revert the changes.
-This can be overridden by adding a `-f`/`--force` option.
-
-git pre-commit hook
--------------------
-
-If you want to run `uncrustify.sh` automatically for changes you make, you can
-configure a pre-commit hook using `admin/git-pre-commit`:
- 1. Copy the `git-pre-commit` script to .git/hooks/pre-commit.
- 2. Specify the path to uncrustify for the hook if you have not already done
- so:
- git config hooks.uncrustifypath /path/to/uncrustify
- 3. Set the operation mode for the hook:
- git config hooks.uncrustifymode check
- git config hooks.copyrightmode update
-
-With this configuration, all source files modified in the commit are run
-through uncrustify and checked for correct copyright headers.
-If any file would be changed by `uncrustify.sh`, the names of those files are
-reported and the commit is prevented. The issues can be fixed by running
-`uncrustify.sh` manually.
-
-To disable the hook without removing the `pre-commit` file, you can set
-
- git config hooks.uncrustifymode off
- git config hooks.copyrightmode off
-
-To disable it temporarily for a commit, set NO_FORMAT_CHECK environment
-variable. For example,
-
- NO_FORMAT_CHECK=1 git commit -a
-
-You can also run `git commit --no-verify`, but that also disables other hooks,
-such as the Change-Id commit-msg hook used by Gerrit.
-
-Note that when you run `git commit --amend`, the hook is only run for the
-changes that are getting amended, not for the whole commit. During a rebase,
-the hook is not run.
-
-The actual work is done by the admin/uncrustify.sh script, which gets
-run with the 'check-index' action, and with `--uncrustify` and `--copyright`
-getting set according to the `git config` settings.
-
-`reformat_all.sh`
------------------
-
-This script runs uncrustify, `copyright.py`, or the include sorter for all
-applicable files in the source tree. See `reformat_all.sh -h` for the
-invocation.
-
-The script can also produce the list of files for which these commands would be
-run. To do this, specify `list-files` on the command line and use
-`--filter=<type>` to specify which command to get the file list for. This can
-be used together with, e.g., `xargs` to run other scripts on the same set of
-files.
-
-For all the operations, it is also possible to apply patters (of the same style
-that various git commands accept, i.e., `src/*.cpp` matches all `.cpp` files
-recursively under `src/`). The patterns can be specified with
-`--pattern=<pattern>`, and multiple `--pattern` arguments can be given.
-
-As with `uncrustify.sh`, `-f`/`--force` is necessary if the working tree and
-the git index do not match.
-
-
-Using git filters
-=================
-
-An alternative to using a pre-commit hook to automatically apply uncrustify on
-changes is to use a git filter (does not require `uncrustify.sh`, only the
-`.gitattributes` file). You can run
-
- git config filter.uncrustify.clean \
- "/path/to/uncrustify -c admin/uncrustify.cfg -q -l cpp"
-
-To configure a filter for all files that specify `filter=uncrustify` attribute.
-
-The pre-commit hook + manually running `uncrustify.sh` gives better/more
-intuitive control (with the filter, it is possible to have a work tree that is
-different from HEAD and still have an empty `git diff`) and provides better
-performance for changes that modify many files. It is the only way that
-currently also checks the copyright headers.
-
-The filter allows one to transparently merge branches that have not been run
-through uncrustify, and is applied more consistently (the pre-commit hook is
-not run for every commit, e.g., during a rebase).
--- /dev/null
+Automatic source code formatting
+================================
+
+.. highlight:: bash
+
+The source code can be automatically formatted using uncrustify, an automatic
+source code formatting tool, to follow the guidelines in
+:doc:`formatting`.
+Additionally, Python scripts are used for a few other automatic
+formatting/checking tasks. The overview tools page contains a list of these
+tools: :ref:`dev-formatting-tools`.
+This page provides more details for uncrustify and copyright scripts.
+
+Jenkins uses these same scripts (in particular, ``uncrustify.sh`` and the
+``check-source`` target) to enforce that the code stays invariant under such
+formatting.
+
+Setting up uncrustify
+---------------------
+
+A patched version of uncrustify is used for |Gromacs|. To set this up, you need
+to do these (once):
+
+1. Change to a directory under which you want to build uncrustify and run::
+
+ git clone -b gromacs git://github.com/rolandschulz/uncrustify.git
+ cd uncrustify
+ ./configure
+ make
+
+2. Copy the binary ``src/uncrustify`` into a directory of your choice
+ (``/path/to/uncrustify`` below).
+
+Alternatively, if you are running Linux, you can try whether the binary from
+http://redmine.gromacs.org/issues/845 works for you.
+
+In order to use the binary for ``uncrustify.sh`` and for the pre-commit hook, you
+also need to run this in each of your |Gromacs| repositories::
+
+ git config hooks.uncrustifypath /path/to/uncrustify
+
+Alternatively, if you just want to use ``uncrustify.sh``, you can set the
+``UNCRUSTIFY`` environment variable to ``/path/to/uncrustify``.
+
+Using the pre-commit hook or git filters needs additional setup; see the
+respective sections below.
+
+What is automatically formatted?
+--------------------------------
+
+To identify which files are subject to automatic formatting, the scripts use
+git filters, specified in ``.gitattributes`` files. Only files that have the
+attribute ``filter`` set to one of the below values are processed:
+
+- ``filter=uncrustify``: uncrustify is run, copyright headers are checked, and
+ include order is enforced
+- ``filter=uncrustify_only``: only uncrustify is run
+- ``filter=includesort``: include order is enforced and copyright headers are
+ checked
+- ``filter=copyright``: only copyright headers are checked
+
+Other files are ignored by ``uncrustify.sh`` and ``reformat_all.sh`` scripts (see
+below).
+
+
+Scripts
+-------
+
+``copyright.py``
+^^^^^^^^^^^^^^^^
+
+This script provides low-level functionality to check and update copyright
+headers in C/C++ source files, as well as in several other types of files like
+CMake and Python scripts.
+
+This file is also used as a loadable Python module for kernel generators, and
+provides the functionality to generate conformant copyright headers for such
+scripts.
+
+The script is similar to uncrustify in that there is rarely need to run it
+directly, but instead the bash scripts below use it internally. You can run
+the script with ``--help`` option if you want to see what all options it provides
+if you need to do some maintenance on the copyright headers themselves.
+
+``uncrustify.sh``
+^^^^^^^^^^^^^^^^^
+
+This script runs uncrustify and ``copyright.py`` on modified files and
+reports/applies the results.
+By default, the current HEAD commit is compared to the work tree,
+and files that
+
+1. are different between these two trees and
+2. change under uncrustify and/or have outdated copyright header
+
+are reported. This behavior can be changed by
+
+1. Specifying an ``--rev=REV`` argument, which uses ``REV`` instead of HEAD as
+ the base of the comparison. A typical use case is to specify ``--rev=HEAD^``
+ to check the HEAD commit.
+2. Specifying an action:
+
+ - ``check-*``: reports the files that uncrustify changes
+ - ``diff-*``: prints the actual diff of what would change
+ - ``update-*``: applies the changes to the repository
+ - ``*-workdir``: operates on the working directory (files on disk)
+ - ``*-index``: operates on the index of the repository
+
+ For convenience, if you omit the workdir/index suffix, workdir is assumed
+ (i.e., ``diff`` equals ``diff-workdir``).
+3. Specifying ``--uncrustify=off``, which does not run uncrustify.
+4. Specifying ``--copyright=<mode>``, which alters the level of copyright
+ checking is done:
+
+ ``off``
+ does not check copyright headers at all
+ ``year``
+ only update copyright year in new-format copyright headers
+ ``add``
+ in addition to ``year``, add copyright headers to files that do not
+ have any
+ ``update``
+ in addition to ``year`` and ``add``, also update new-format copyright
+ headers if they are broken or outdated
+ ``replace``
+ replace any copyright header with a new-format copyright header
+ ``full``
+ do all of the above
+
+By default, ``update-*`` refuses to update dirty files (i.e., that differ
+between the disk and the index) to make it easy to revert the changes.
+This can be overridden by adding a ``-f``/``--force`` option.
+
+git pre-commit hook
+^^^^^^^^^^^^^^^^^^^
+
+If you want to run ``uncrustify.sh`` automatically for changes you make, you can
+configure a pre-commit hook using ``admin/git-pre-commit``:
+
+1. Copy the ``git-pre-commit`` script to .git/hooks/pre-commit.
+2. Specify the path to uncrustify for the hook if you have not already done
+ so::
+
+ git config hooks.uncrustifypath /path/to/uncrustify
+
+3. Set the operation mode for the hook::
+
+ git config hooks.uncrustifymode check
+ git config hooks.copyrightmode update
+
+With this configuration, all source files modified in the commit are run
+through uncrustify and checked for correct copyright headers.
+If any file would be changed by ``uncrustify.sh``, the names of those files are
+reported and the commit is prevented. The issues can be fixed by running
+``uncrustify.sh`` manually.
+
+To disable the hook without removing the ``pre-commit`` file, you can set ::
+
+ git config hooks.uncrustifymode off
+ git config hooks.copyrightmode off
+
+To disable it temporarily for a commit, set NO_FORMAT_CHECK environment
+variable. For example, ::
+
+ NO_FORMAT_CHECK=1 git commit -a
+
+You can also run ``git commit --no-verify``, but that also disables other hooks,
+such as the Change-Id ``commit-msg`` hook used by Gerrit.
+
+Note that when you run ``git commit --amend``, the hook is only run for the
+changes that are getting amended, not for the whole commit. During a rebase,
+the hook is not run.
+
+The actual work is done by the ``admin/uncrustify.sh`` script, which gets
+run with the ``check-index`` action, and with ``--uncrustify`` and ``--copyright``
+getting set according to the ``git config`` settings.
+
+``reformat_all.sh``
+^^^^^^^^^^^^^^^^^^^
+
+This script runs uncrustify, ``copyright.py``, or the include sorter for all
+applicable files in the source tree. See ``reformat_all.sh -h`` for the
+invocation.
+
+The script can also produce the list of files for which these commands would be
+run. To do this, specify ``list-files`` on the command line and use
+``--filter=<type>`` to specify which command to get the file list for. This can
+be used together with, e.g., ``xargs`` to run other scripts on the same set of
+files.
+
+For all the operations, it is also possible to apply patters (of the same style
+that various git commands accept, i.e., ``src/*.cpp`` matches all ``.cpp`` files
+recursively under ``src/``). The patterns can be specified with
+``--pattern=<pattern>``, and multiple ``--pattern`` arguments can be given.
+
+As with ``uncrustify.sh``, ``-f``/``--force`` is necessary if the working tree and
+the git index do not match.
+
+
+Using git filters
+-----------------
+
+An alternative to using a pre-commit hook to automatically apply uncrustify on
+changes is to use a git filter (does not require ``uncrustify.sh``, only the
+``.gitattributes`` file). You can run ::
+
+ git config filter.uncrustify.clean \
+ "/path/to/uncrustify -c admin/uncrustify.cfg -q -l cpp"
+
+To configure a filter for all files that specify ``filter=uncrustify`` attribute.
+
+The pre-commit hook + manually running ``uncrustify.sh`` gives better/more
+intuitive control (with the filter, it is possible to have a work tree that is
+different from HEAD and still have an empty ``git diff``) and provides better
+performance for changes that modify many files. It is the only way that
+currently also checks the copyright headers.
+
+The filter allows one to transparently merge branches that have not been run
+through uncrustify, and is applied more consistently (the pre-commit hook is
+not run for every commit, e.g., during a rebase).
@INCLUDE = Doxyfile-version
LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/DoxygenLayout.xml
INPUT = @CMAKE_CURRENT_SOURCE_DIR@ \
- @CMAKE_SOURCE_DIR@/docs/dev-manual \
@CMAKE_SOURCE_DIR@/src \
@CMAKE_SOURCE_DIR@/share/template
FILE_PATTERNS = *.c *.cpp *.h *.md
# FILE_PATTERNS += *.cu *.cuh
EXAMPLE_PATH = @CMAKE_SOURCE_DIR@
RECURSIVE = YES
-EXCLUDE = @CMAKE_CURRENT_SOURCE_DIR@/examples \
- @CMAKE_SOURCE_DIR@/src/contrib \
+EXCLUDE = @CMAKE_SOURCE_DIR@/src/contrib \
@CMAKE_SOURCE_DIR@/src/external \
@CMAKE_SOURCE_DIR@/src/gromacs/selection/parser.cpp \
@CMAKE_SOURCE_DIR@/src/gromacs/selection/parser.h \
# These pages include documentation that does not belong to the public API
# documentation; exclude them from the generated documentation
EXCLUDE += @CMAKE_CURRENT_SOURCE_DIR@/lib
-EXCLUDE += @CMAKE_SOURCE_DIR@/docs/dev-manual
INTERNAL_DOCS = NO
HIDE_UNDOC_CLASSES = YES
the public API documentation.
The checks should be self-evident from the source code of the script
-(they are also described in docs/dev-manual/gmxtree.md).
+(they are also described in docs/dev-manual/gmxtree.rst).
All the logic of parsing the Doxygen XML output and creating a GROMACS-specific
representation of the source tree is separated into separate Python modules
(doxygenxml.py and gmxtree.py, respectively). Similarly, logic for handling
+++ /dev/null
-// The struct itself is not documented; other comments within the declaration
-// are ignored.
-
-struct t_struct {
-
- // The comment tries to document both members at once, but it only
- // applies to the first. The second produces warnings about missing
- // documentation (if the enclosing struct was documented).
-
- //! Angle parameters.
- double alpha, beta;
-};
-
-
-// This does not produce any brief documentation.
-// An explicit \brief is required, or //! (C++) or /** */ (C) should be used.
-
-/*! Brief comment. */
-int gmx_function();
-
-
-// This does not produce any documentation at all, since a ! is missing at
-// the beginning.
-
-/* \brief
- * Brief description.
- *
- * More details.
- */
-int gmx_function();
-
-
-// This puts the whole paragraph into the brief description.
-// A short description is preferable, separated by an empty line from the rest
-// of the text.
-
-/*! \brief
- * Brief description. The description continues with all kinds of details about
- * what the function does and how it should be called.
- */
-int gmx_function();
-
-
-// This may be a Doxygen bug, but this does not produce any brief description.
-
-/** \internal Brief description. */
-int gmx_function();
-
-
-// If the first declaration below appears in a header, and the second in a
-// source file, then Doxygen does not associate them correctly and complains
-// about missing documentation for the latter. The solution is to explicitly
-// add a namespace prefix also in the source file, even though the compiler
-// does not require it.
-
-// Header file
-//! Example function with a namespace-qualified parameter type.
-int gmx_function(const gmx::SomeClass ¶m);
-
-// Source file
-using gmx::SomeClass;
-
-int gmx_function(const SomeClass ¶m);
-
-
-// This puts the namespace into the mentioned module, instead of the contents
-// of the namespace. \addtogroup should go within the innermost scope.
-
-//! \addtogroup module_example
-//! \{
-
-namespace gmx
-{
-
-//! Function intended to be part of module_example.
-int gmx_function();
-
-}
+++ /dev/null
-/*! \defgroup module_example "Example module (example)"
- * \ingroup group_utilitymodules
- * \brief
- * Brief description for the module.
- *
- * Detailed description of the module. Can link to a separate Doxygen page for
- * overview, and/or describe the most important headers and/or classes in the
- * module as part of this documentation.
- *
- * For modules not exposed publicly, \\libinternal can be added at the
- * beginning (before \\defgroup).
- *
- * \author Author Name <author.name@email.com>
- */
-
-// In other code, use \addtogroup module_example and \ingroup module_example to
-// add content (classes, functions, etc.) onto the module page.
+++ /dev/null
-/*! \libinternal \file
- * \brief
- * ...
- *
- * The examples below assume that the file is documented like this:
- * with an \\libinternal definition at the beginning, with an intent to not
- * expose anything from the file in the public API. Things work similarly for
- * the full documentation if you replace \\libinternal with \\internal
- * everywhere in the example.
- *
- * \ingroup module_example
- */
-
-
-/*! \brief
- * Brief description for a free function.
- *
- * A free function is not extracted into the documentation unless the enclosing
- * scope (in this case, the file) is. So a \\libinternal is not necessary.
- */
-void gmx_function();
-
-// Assume that the module_example group is defined in the public API.
-
-//! \addtogroup module_example
-//! \{
-
-//! \cond libapi
-/*! \brief
- * Brief description for a free function within \\addtogroup.
- *
- * In this case, the enclosing scope is actually the module_example group,
- * which is documented, so the function needs to be explicitly excluded.
- * \\libinternal does not work, since it would produce warnings about an
- * undocumented function, so the whole declaration is hidden from Doxygen.
- */
-void gmx_function();
-//! \endcond
-
-//! \}
-
-// For modules that are only declared in the library API, \addtogroup
-// cannot be used without an enclosing \cond. Otherwise, it will create
-// a dummy module with the identifier as the name...
-
-//! \cond libapi
-//! \addtogroup module_libmodule
-//! \{
-
-/*! \brief
- * Brief description.
- *
- * No \\libinternal is necessary here because of the enclosing \\cond.
- */
-void gmx_function();
-
-//! \}
-//! \endcond
-
-// An alternative to the above is use this, if the enclosing scope is only
-// documented in the library API:
-
-//! \libinternal \addtogroup module_libmodule
-//! \{
-
-//! Brief description.
-void gmx_function()
-
-//! \}
-
-/*! \libinternal \brief
- * Brief description for a struct.
- *
- * Documented structs and classes from headers are always extracted into the
- * documentation, so \\libinternal is necessary to exclude it.
- * Currently, undocumented structs/classes do not produce warnings, so \\cond
- * is not necessary.
- */
-struct t_example
-{
- int member1; //!< Each non-private member should be documented.
- bool member2; //!< Otherwise, Doxygen will produce warnings.
-};
-
-// This namespace is documented in the public API.
-namespace gmx
-{
-
-//! \cond libapi
-/*! \brief
- * Brief description for a free function within a documented namespace.
- *
- * In this case, the enclosing scope is the documented namespace,
- * so a \\cond is necessary to avoid warnings.
- */
-void gmx_function();
-//! \endcond
-
-/*! \brief
- * Class meant for subclassing only within the module, but the subclasses will
- * be public.
- *
- * This base class still provides public methods that are visible through the
- * subclasses, so it should appear in the public documentation.
- * But it is not marked with \\inpublicapi.
- */
-class BaseClass
-{
- public:
- /*! \brief
- * A public method.
- *
- * This method also appears in the documentation of each subclass in
- * the public and library API docs.
- */
- void method();
-
- protected:
- // The \cond is necessary to exlude this documentation from the public
- // API, since the public API does not support subclassing.
- //! \cond internal
- //! A method that only subclasses inside the module see.
- void methodForSubclassToCall();
-
- //! A method that needs to be implemented by subclasses.
- virtual void virtualMethodToImplement() = 0;
- //! \endcond
-};
-
-} // namespace gmx
+++ /dev/null
-/*! \file
- * \brief
- * Declares a collection of functions for performing a certain task.
- *
- * More details can go here.
- *
- * \author Example Author <example@author.com>
- * \inpublicapi
- * \ingroup module_mymodule
- */
-
-/*! \addtogroup module_mymodule */
-/*! \{ */
-
-/*! \brief
- * Brief description for the data structure.
- *
- * More details.
- *
- * \inpublicapi
- */
-typedef struct {
- /** Brief description for member. */
- int member;
- int second; /**< Brief description for the second member. */
- /*! \brief
- * Brief description for the third member.
- *
- * Details.
- */
- int third;
-} gmx_mystruct_t;
-
-/*! \brief
- * Performs a simple operation.
- *
- * \param[in] value Input value.
- * \returns Computed value.
- *
- * Detailed description.
- * \\inpublicapi cannot be used here, because Doxygen only allows a single
- * group for functions, and module_mymodule is the preferred group.
- */
-int gmx_function(int value);
-
-/* Any . in the brief description should be escaped as \. */
-/** Brief description for this function. */
-int gmx_simple_function();
-
-/*! \} */
+++ /dev/null
-/*! \libinternal \file
- * \brief
- * Declares gmx::MyClass.
- *
- * More details. The documentation is still extracted for the class even if
- * this whole comment block is missing.
- *
- * \author Example Author <example@author.com>
- * \inlibraryapi
- * \ingroup module_mymodule
- */
-
-namespace gmx
-{
-
-/*! \libinternal
- * \brief
- * Brief description for the class.
- *
- * More details. The \\libinternal tag is required for classes, since they are
- * extracted into the documentation even in the absence of documentation for
- * the enclosing scope.
- * The \\libinternal tag is on a separate line because of a bug in Doxygen
- * 1.8.5 (only affects \\internal, but for clarity it is also worked around
- * here).
- *
- * \inlibraryapi
- * \ingroup module_mymodule
- */
-class MyClass
-{
- public:
- // Trivial constructors or destructors do not require documentation.
- // But if a constructor takes parameters, it should be documented like
- // methods below.
- MyClass();
- ~MyClass();
-
- /*! \brief
- * Brief description for the method.
- *
- * \param[in] param1 Description of the first parameter.
- * \param[in] param2 Description of the second parameter.
- * \returns Description of the return value.
- * \throws std::bad_alloc if out of memory.
- *
- * More details describing the method. It is not an error to put this
- * above the parameter block, but most existing code has it here.
- */
- int myMethod(int param1, const char *param2) const;
-
- //! Brief description for the accessor.
- int simpleAccessor() const { return var_; }
- /*! \brief
- * Alternative, more verbose way of specifying a brief description.
- */
- int anotherAccessor() const;
- /*! \brief
- * Brief description for another accessor that is so long that it does
- * not conveniently fit on a single line cannot be specified with //!.
- */
- int secondAccessor() const;
-
- private:
- // Private members (whether methods or variables) are currently ignored
- // by Doxygen, so they don't need to be documented. Documentation
- // doesn't hurt, though.
- int var_;
-};
-
-} // namespace gmx
+++ /dev/null
-Using Doxygen {#page_doxygen}
-=============
-
-This page documents how Doxygen is set up in the \Gromacs source tree,
-as well as guidelines for adding new Doxygen comments. Examples are included,
-as well as tips and tricks for avoiding Doxygen warnings. The guidelines focus
-on C++ code and other new code that follows the new module layout.
-Parts of the guidelines are still applicable to documenting older code (e.g.,
-within `gmxlib/` or `mdlib/`), in particular the guidelines about formatting
-the Doxygen comments and the use of \c \\internal.
-\ref page_codelayout documents the overall structure of the documentation.
-
-To get started quickly, you only need to read the first two sections to
-understand the overall structure of the documentation, and take a look at the
-examples at the end. The remaining sections provide the details for
-understanding why the examples are the way they are, and for more complex
-situations. They are meant more as a reference to look up solutions for
-particular problems, rather than single-time reading. To understand or find
-individual Doxygen commands, you should first look at Doxygen documentation
-(http://www.stack.nl/~dimitri/doxygen/manual/index.html).
-
-
-Documentation flavors
-=====================
-
-The \Gromacs source tree is set up to produce three different levels of Doxygen
-documentation:
-
-1. Public API documentation (suffix `-user`), which documents functions and
- classes exported from the library and intended for use outside the \Gromacs
- library.
-2. Library API documentation (suffix `-lib`), which additionally includes
- functions and classes that are designed to be used from other parts of
- \Gromacs, as well as some guidelines that are mostly of interest to
- developers.
-3. Full documentation (suffix `-full`), which includes (nearly) all (documented)
- functions and classes in the source tree.
-
-Each subsequent level of documentation includes all the documentation from the
-levels above it. The suffixes above refer to the suffixes of Doxygen input and
-output files, as well as the name of the output directory. When all the
-flavors have been built, the front pages of the documentation contain links to
-the other flavors, and explain the differences in more detail.
-
-As a general guideline, the public API documentation should be kept free of
-anything that a user linking against an unmodified \Gromacs does not see.
-In other words, the public API documentation should mainly document the
-contents of installed headers, and provide the necessary overview of using
-those. Also, verbosity requirements for the public API documentation are
-higher: ideally, readers of the documentation could immediately start using the
-API based on the documentation, without any need to look at the implementation.
-
-Similarly, the library API documentation should not contain things that other
-modules in \Gromacs can or should never call. In particular, anything declared
-locally in source files should be only available in the full documentation.
-Also, if something is documented, and is not identified to be in the library
-API, then it should not be necessary to call that function from outside its
-module.
-
-
-Building the documentation
-==========================
-
-If you simply want to see up-to-date documentation, you can go to
-http://jenkins.gromacs.org/job/Documentation_Nightly_master/javadoc/html-lib/index.xhtml
-to see the documentation for the current development version.
-Jenkins also runs Doxygen for all changes pushed to Gerrit for
-release-5-0 and master branches, and the
-resulting documentation can be viewed from the link posted by Jenkins. The
-Doxygen build is marked as unstable if it introduces any Doxygen warnings.
-
-You may need to build the documentation locally if you want to check the
-results after adding/modifying a significant amount of comments. This is
-recommended in particular if you do not have much experience with Doxygen.
-It is a good idea to build with all the different settings to see that the
-result is what you want, and that you do not produce any warnings.
-For local work, it is generally a good idea to set `GMX_COMPACT_DOXYGEN=ON`
-CMake option, which removes some large generated graphs from the documentation
-and speeds up the process significantly.
-
-All files related to Doxygen reside in the `docs/doxygen/` subdirectory in the source
-and build trees. In a freshly checked out source tree, this directory contains
-various `Doxyfile-*.cmakein` files. When you run CMake, corresponding files
-`Doxyfile-user`, `Doxyfile-lib`, and `Doxyfile-full` are generated at the
-corresponding location in the build tree. There is also a
-`Doxyfile-common.cmakein`, which is used to produce `Doxyfile-common`.
-This file contains settings that are shared between all the input files.
-`Doxyfile-compact` provides the extra settings for `GMX_COMPACT_DOXYGEN=ON`.
-
-You can run Doxygen directly with one of the generated files (all output will
-be produced under the current working directory), or build one of the
-`doxygen-user`, `doxygen-lib`, and `doxygen-full` targets. The targets run
-Doxygen in a quieter mode and only show the warnings if there were any, and put
-the output under `docs/html/doxygen/` in the build tree, so that the Doxygen
-build cooperates with the broader `webpage` target.
-The `doxygen-all` target builds all three targets with less typing.
-
-The generated documentation is put under `html-user/`, `html-lib/`, and/or
-`html-full/`. Open `index.xhtml` file from one of
-these subdirectories to start browsing (for \Gromacs developers, the
-`html-lib/` is a reasonable starting point). Log files with all Doxygen
-warnings are also produced as `docs/doxygen/doxygen-*.log`, so you can inspect them after
-the run.
-
-You will need Doxygen 1.8.5 to build the current documentation. Other versions
-may work, but likely also produce warnings. Additionally,
-[graphviz](http://www.graphviz.org) and
-[mscgen](http://www.mcternan.me.uk/mscgen/) are required for some graphs in
-the documentation, and `latex` for formulas. Working versions are likely
-available through most package managers. It is possible to build the
-documentation without these tools, but you will see some errors and the related
-figures will be missing from the documentation.
-
-
-General guidelines for Doxygen markup {#section_doxygen_guidelines}
-=====================================
-
-Doxygen provides quite a few different alternative styles for documenting the
-source code. There are subtleties in how Doxygen treats the different types of
-comments, and this also depends somewhat on the Doxygen configuration. It is
-possible to change the meaning of a comment by just changing the style of
-comment it is enclosed in. To avoid such issues, and to avoid needing to
-manage all the alternatives, a single style throughout the source tree is
-preferable. When it comes to treatment of styles, \Gromacs uses the default
-Doxygen configuration with one exception: `JAVADOC_AUTOBRIEF` is set ON to
-allow more convenient one-line brief descriptions in C code.
-
-Majority of existing comments in \Gromacs uses Qt-style comments (`/*!` and
-`//!` instead of `/*``*` and `///`, \c \\brief instead of \c \@brief etc.),
-so these should be used also for new documentation. There is a single
-exception for brief comments in C code; see below.
-
-Similarly, existing comments use `/*!` for multiline comments in both C and
-C++ code, instead of using multiple `//!` lines for C++. The rationale is that
-since the code will be a mixture of both languages for a long time, it is more
-uniform to use similar style in both. Also, since files will likely transition
-from C to C++ gradually, rewriting the comments because of different style
-issues should not generally be necessary. Finally, multi-line `//!` comments
-can work differently depending on Doxygen configuration, so it is better to
-avoid that ambiguity.
-
-When adding comments, ensure that a short brief description is always produced.
-This is used in various listings, and should briefly explain the purpose of the
-method without unnecessarily expanding those lists.
-The basic guideline is to start all comment blocks with \c \\brief (possibly
-after some other Doxygen commands).
-If you want to avoid the \c \\brief for one-liners, you can use `//!`, but the
-description must fit on a single line; otherwise, it is not interpreted as a
-brief comment. Note in particular that a simple `/*!` without a \c \\brief
-does not produce a brief description.
-Also note that \c \\brief marks the whole following paragraph as a brief
-description, so you should insert an empty line after the intended brief
-description.
-
-In C code, `//` comments must be avoided because some compilers do not like
-them. If you want to avoid the \c \\brief for one-liners in C code, use
-`/*``*` instead of `//!`. If you do this, the brief description should not
-contain unescaped periods except at the end. Because of this, you should
-prefer `//!` in C++ code.
-
-Put the documentation comments in the header file that contains the
-declaration, if such a header exists.
-Implementation-specific comments that do not influence how a method
-is used can go into the source file, just before the method definition, with an
-\c \\internal tag in the beginning of the comment block. Doxygen-style comments
-within functions are not generally usable.
-
-At times, you may need to exclude some part of a header or a source file such
-that Doxygen does not see it at all. In general, you should try to avoid this,
-but it may be necessary to remove some functions that you do not want to appear
-in the public API documentation, and which would generate warnings if left
-undocumented, or to avoid Doxygen warnings from code it does not understand.
-Prefer \c \\cond and \c \\endcond to do this. If \c \\cond does not work for
-you, you can also use \c \#ifndef `DOXYGEN`. If you exclude a class method in
-a header, you also need to exclude it in the source code to avoid warnings.
-
-
-\Gromacs specifics
-=================
-
-The general guidelines on the style of Doxygen comments were given above.
-This section introduces \Gromacs specific constructs currently used in Doxygen
-documentation, as well as how \Gromacs uses Doxygen groups to organize the
-documentation.
-
-Some consistency checks are done automatically using custom scripts.
-See \ref page_dev_gmxtree for details.
-
-Controlling documentation visibility
-------------------------------------
-
-To control in which level of documentation a certain function appears, three
-different mechanisms are used:
-* Global Doxygen configuration. This is mainly used to include
- declarations local to source files only in the full documentation.
- You can find the details from the `Doxyfile-*.cmakein` files, and some of
- them are also mentioned below on individual code constructs.
-* The standard Doxygen command \c \\internal marks the documentation to be only
- extracted into the full documentation (`INTERNAL_DOCS` is `ON` only for the
- full documentation). This should be used as a first command in a comment
- block to exclude all the documentation. It is possible to use \c \\internal
- and \c \\endinternal to exclude individual paragraphs, but \c \\if `internal`
- is preferred (see below).
- In addition, \Gromacs-specific custom Doxygen command \c \\libinternal is
- provided, which should be used the same way to exclude the documentation from
- the public API documentation. This command expands to either \c \\internal
- or to a no-op, depending on the documentation level.
-* Doxygen commands \c \\if and \c \\cond can be used with section names
- `libapi` and `internal` to only include the documentation in library API and
- the full documentation, respectively. `libapi` is also defined in the full
- documentation. These are declared using `ENABLED_SECTIONS` in the Doxygen
- configuration files.
-
-Examples of locations where it is necessary to use these explicit commands are
-given below in the sections on individual code constructs.
-
-Modules as Doxygen groups
--------------------------
-
-As described in \ref page_codelayout, each subdirectory under `src/gromacs/`
-represents a _module_, i.e., a somewhat coherent collection of routines.
-Doxygen cannot automatically generate a list of routines in a module; it only
-extracts various alphabetical indexes that contain more or less all documented
-functions and classes. To help reading the documentation, the routines for a
-module should be visible in one place.
-
-\Gromacs uses Doxygen groups to achieve this: for each documented module, there
-is a \c \\defgroup definition for the module, and all the relevant classes and
-functions need to be manually added to this group using \c \\ingroup and
-\c \\addtogroup.
-The group page also provides a natural place for overview documentation about
-the module, and can be navigated to directly from the "Modules" tab in the
-generated documentation.
-
-Some notes about using \c \\addtogroup are in order:
-* \c \\addtogroup only adds the elements that it directly contains into the
- group. If it contains a namespace declaration, only the namespace is added
- to the group, but none of the namespace contents are. For this reason,
- \c \\addtogroup should go within the innermost scope, around the members that
- should actually be added.
-* If the module should not appear in the public API documentation, its
- definition (\c \\defgroup) should be prefixed with a \c \\libinternal.
- In this case, also all \c \\addtogroup commands for this module should be
- similarly prefixed. Otherwise, they create the group in the public API
- documentation, but without any of the content from the \c \\defgroup
- definition. This may also cause the contents of the \c \\addtogroup section
- to appear in the public API documentation, even if it otherwise would not.
-
-Public API and library API groups
----------------------------------
-
-In addition to the module groups, two fixed groups are provided:
-`group_publicapi` and `group_libraryapi`. Classes and files can be added to
-these groups using \Gromacs specific custom \c \\inpublicapi and
-\c \\inlibraryapi commands. The generated group documentation pages are not
-very useful, but annotated classes and files show the API definition under the
-name, making this information more easily accessible. These commands in
-file-level comments are also used for some automatic intermodule dependency
-validation (see below).
-
-Note that functions, enumerations, and other entities that do not have a
-separate page in the generated documentation can only belong to one group;
-in such a case, the module group is preferred over the API group.
-
-
-Documenting specific code constructs
-====================================
-
-This section describes the techical details and some tips and tricks for
-documenting specific code constructs such that useful documentation is
-produced. If you are wondering where to document a certain piece of
-information, see the documentation structure section on \ref page_codelayout.
-The focus of the documentation should be on the overview content: Doxygen pages
-and the module documentation. An experienced developer can relatively easily
-read and understand individual functions, but the documentation should help
-in getting the big picture.
-
-Doxygen pages
--------------
-
-The pages that are accessible through navigation from the front page are
-written using Markdown and are located under `docs/doxygen/`. Each page should be
-placed in the page hierarchy by making it a subpage of another page, i.e., it
-should be referenced once using \c \\subpage. `mainpage.md` is the root of the
-hierarchy.
-
-There are two subdirectories, `user/` and `lib/`, determining the highest
-documentation level where the page appears. If you add pages to `lib/`, ensure
-that there are no references to the page from public API documentation.
-\c \\if `libapi` can be used to add references in content that is otherwise
-public.
-Generally, the pages should be on a high enough level and provide overview
-content that is useful enough such that it is not necessary to exclude them
-from the library API documentation.
-
-Modules
--------
-
-For each module, decide on a header file that is the most important one for
-that module (if there is no self-evident header, it may be better to designate,
-e.g., module-doc.h for this purpose, but this is currently not done for any
-module). This header should contain the \c \\defgroup definition for the
-module. The name of the group should be `module_`<em>name</em>, where _name_
-is the name of the subdirectory that hosts the module.
-
-The module should be added to an appropriate group (see `docs/doxygen/misc.cpp` for
-definitions) using \c \\ingroup to organize the "Modules" tab in the generated
-documentation.
-
-One or more contact persons who know about the contents of the module should be
-listed using \c \\author commands. This provides a point of contact if one
-has questions.
-
-Classes/structs
----------------
-
-Classes and structs in header files appear always in Doxygen documentation,
-even if their enclosing file is not documented. So start the documentation
-blocks of classes that are not part of the public API with \c \\internal or
-\c \\libinternal. Classes declared locally in source files or in unnamed
-namespaces only appear in the full documentation.
-
-If a whole class is not documented, this does not currently generate any
-warning. The class is simply exluded from the documentation. But if a member
-of a documented class is not documented, a warning is generated. Guidelines for
-documenting free functions apply to methods of a class as well.
-
-For base classes, the API classification (\c \\inpublicapi or
-\c \\inlibraryapi) should be based on where the class is meant to be
-subclassed. The visibility (\c \\internal or \c \\libinternal), in contrast,
-should reflect the API classification of derived classes such that the base
-class documentation is always generated together with the derived classes.
-
-For classes that are meant to be subclassed and have protected members, the
-protected members should only appear at the documentation level where the class
-is meant to be subclassed. For example, if a class is meant to be subclassed
-only within a module, the protected members should only appear in the
-full documentation. This can be accomplished using \c \\cond (note that you
-will need to add the \c \\cond command also to the source files to hide the
-same methods from Doxygen, otherwise you will get confusing warnings).
-
-Methods/functions/enums/macros
-------------------------------
-
-These items do not appear in the documentation unless their enclosing scope is
-documented. For class members, the scope is the class; otherwise, it is the
-namespace if one exists, or the file. An \c \\addtogroup can also define a
-scope if the group has higher visibility than the scope outside it.
-So if a function is not within a namespace (mostly applicable to C code) and
-has the same visibility as its enclosing file, it is not necessary to add a
-\c \\internal or \c \\libinternal.
-
-Static functions are currently extracted for all documentation flavors to allow
-headers to declare `static inline` functions (used in, for example, math code).
-Functions in anonymous namespaces are only extracted into the full
-documentation. Together with the above rules, this means that you should avoid
-putting a `static` function within a documented namespace, even within source
-files, or it may inadvertently appear in the public API documentation.
-
-If you want to exclude an item from the documentation, you need to put in
-inside a \c \\cond block such that Doxygen does not see it.
-Otherwise, a warning for an undocumented function is generated. You need to
-enclose both the declaration and the definition with \c \\cond.
-
-Files
------
-
-Each documented file should start with a documentation block (right after the
-copyright notice) that documents the file. See the examples section for exact
-formatting. Things to note:
-* Please do not specify the file name explicitly after \c \\file. By default,
- a file comment applies to the file it is contained in, and an explicit file
- name only adds one more thing that can get out of date.
-* \c \\brief cannot appear on the same line as the \c \\file, but should be on
- the next line.
-* \c \\internal or \c \\libinternal should indicate where the header is visible.
- As a general guideline, all installed headers should appear in the public API
- documentation, i.e., not contain these commands. If nothing else, then to
- document that it does not contain any public API functions. Headers that
- declare anything in the library API should be marked with \c \\libinternal,
- and the rest with \c \\internal.
-* All source files, as well as most test files, should be documented with
- \c \\internal, since they do not provide anything to public or library API,
- and this avoids unintentionally extracting things from the file into those
- documentations. Shared test files used in tests from other modules should be
- marked with \c \\libinternal.
-* \c \\inpublicapi or \c \\inlibraryapi should be used to indicate where the
- header is meant to be directly included.
-* As with files, one or more contact persons should be listed with \c \\author.
- If you make significant modifications or additions to a file, consider adding
- an \c \\author line for yourself.
-
-Directories
------------
-
-Directory documentation does not typically contain useful information beyond a
-possible brief description, since they correspond very closely to modules, and
-the modules themselves are documented. A brief description is still useful to
-provide a high-level overview of the source tree on the generated "Files" page.
-A reference to the module is typically sufficient as a brief description for a
-directory. All directories are currently documented in
-`docs/doxygen/directories.cpp`.
-
-
-Examples
-========
-
-Basic C++
----------
-
-Here is an example of documenting a C++ class and its containing header file.
-Comments in the code and the actual documentation explain the used Doxygen
-constructs.
-
-\includelineno doxygen-example.cpp
-
-Basic C
--------
-
-Here is another example of documenting a C header file (so avoiding all
-C++-style comments), and including free functions. It also demonstrates the use
-of \c \\addtogroup to add multiple functions into a module group without repeated
-\c \\ingroup tags.
-
-\includelineno doxygen-example.c
-
-Scoping and visibility rules
-----------------------------
-
-The rules where Doxygen expects something to be documented, and when are
-commands like \c \\internal needed, can be complex. The examples below
-describe some of the pitfalls.
-
-\includelineno doxygen-example-scoping.cpp
-
-Module documentation
---------------------
-
-Documenting a new module should place a comment like this in a central header
-for the module, such that the "Modules" tab in the generated documentation can
-be used to navigate to the module.
-
-\includelineno doxygen-example-module.cpp
-
-Common mistakes
----------------
-
-The most common mistake, in particular in C code, is to forget to document the
-file. This causes Doxygen to ignore most comments in the file, so it
-does not validate the contents of the comments either, nor is it possible to
-actually check how the generated documentation looks like.
-
-The following example shows some other common mistakes (and some less common)
-that do not produce correct documentation, as well as Doxygen "features"/bugs
-that can be confusing.
-The issues are explained in normal comments above each code fragment.
-
-\includelineno doxygen-example-issues.cpp
-
-Existing code
--------------
-
-More examples you can find by looking at existing code in the source tree. In
-particular new C++ code such as that in the `src/gromacs/analysisdata/` and
-`src/gromacs/options/` subdirectories contains a large amount of code
-documented mostly along these guidelines. Some comments in
-`src/gromacs/selection/` (in particular, any C-like code) predate the
-introduction of these guidelines, so those are not the best examples.
\endif
This list will hopefully expand over time.
-
-\if libapi
-Additionally, a separate section contains a \subpage page_devmanual, which provides
-resources for developers, such as and documentation for development-time tools
-and guidelines.
-\endif
Documentation for developers
----------------------------
+Resources for developers, e.g., related to guidelines and tools used during
+development.
+
+.. toctree::
+ :maxdepth: 3
+
+ dev-manual/index
+
* `Doxygen public API documentation <doxygen/html-user/index.xhtml>`_
* `Doxygen code documentation <doxygen/html-lib/index.xhtml>`_
This contains the public API documentation as a subset, but also has more
details on the internal implementation of |Gromacs|.
-* `Developer Guide <doxygen/html-lib/page_devmanual.xhtml>`_
- Resources for developers, e.g., related to guidelines and tools used during
- development.
-
Indices and tables
==================
biod.pnpi.spb.ru / alexxy / gromacs.git / commitdiff