GROMACS

For GROMACS 2019, gmxapi doxygen documentation is built with separate targets:

• gmxapi_cppdocs for installed headers, and
• gmxapi_cppdocs_dev for implementation details and verbosity on extension interfaces

HTML output appears in separate build/docs/api-user and build/docs/api-dev directories, respectively. The documentation should be better integrated during GROMACS 2020 development to be discoverable, helpful, and appropriately cross-referenced. This will require some decisions about intended user experience and appropriate technological dependencies.

Establish policies and layout for¶

• external (installed) API documentation
• extension API for plug-in developers
• developer documentation for API and library implementation levels.

Integrate with previous webpage-sphinx and doxygen targets and output.¶

Plan TBD.

Considerations¶

Extension-friendly software documentation usually seems to be most helpful when provided in both a prose / manual / tutorial form as well as an information-dense well-cross-referenced API reference. Both could be provided with the webpage build using Sphinx and auto-documentation. It is also reasonable to leave the API reference in standard doxygen output form, but we could use breathe to extract documentation from the Doxygen XML for building in the Sphinx-based documentation. gmxapi is an external interface that warrants at least some documentation in the same context as the command line interface or file-based input/output. As Python front-end and API documentation begins to be incorporated, it could be appropriate to provide C++ and Python documentation in parallel for the equivalent functionality.

We should note that the target audience of the gmxapi API documentation (researchers, power-users) is different from the target audience for library internal documentation (GROMACS contributors, GROMACS maintainers). It should be very clear which documentation is which, and probably difficult to stumble from one into the other. We don't have to make it quite as hard as in some other software projects to find the library documentation for the implementation of a feature described in the high-level API docs. But as we sharpen the distinction between internal and external interfaces, the distinction in documentation for API levels will necessarily be sharpened, too.