Task #2698

Task #2045: API design and language bindings

gmxapi documentation integration

Added by Eric Irrgang over 2 years ago. Updated 12 months ago.

In Progress


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.


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.


Feature #2985: Python package documentationClosed

Related issues

Related to GROMACS - Task #988: Definition of "public API"New

Associated revisions

Revision aa6a516e (diff)
Added by Eric Irrgang over 1 year ago

gmxapi Python package documentation infrastructure.

  • Begin a documentation tree in python_packaging/documentation.
  • Create a docker image for quick rebuild and review of Sphinx docs.

Refs #2698

Change-Id: Ib05e0309e60bfdadf52dadc7af0942c25c89f1e4

Revision 17779a30 (diff)
Added by Eric Irrgang over 1 year ago

gmxapi Python package documentation layout.

Refs #2698

Change-Id: Id7fb8c6c91640660566394c37e63b5acb8bd9e3d

Revision 41cefdda (diff)
Added by Eric Irrgang over 1 year ago

Import gmxapi docs to main GROMACS docs directory.

This change defers removal of the documentation staged in
python_packaging so to allow rearrangement of the docs in the new
location without risking loss of content or the ability to generate
the previous documentation.

Refs #2698

Change-Id: Ie64585fe519aa37ada9d353f1eccd2daafcdbceb

Revision f29a1758 (diff)
Added by Eric Irrgang over 1 year ago

Build gmxapi documentation in main GROMACS documentation.

  • Update gmxapi Python package installation instructions and remove
  • Minor updates to main installation guide document.

Refs #2698
Refs #2985

Change-Id: I6f1d6e6fe59e618144e4f14c0d2fe9f9b8c2c901

Revision 9124029b (diff)
Added by Eric Irrgang about 1 year ago

Deduplicate gmxapi documentation.

`docs/gmxapi` seems to have settled down and does not have substantial
layout changes from the documentation in python_packaging/documentation.
Compartmentalized doc builds, e.g. with docs.dockerfile, still warrant
a separate simple, so that much is retained. Otherwise, it looks
like documentation for the standalone gmxapi package or development can
be maintained in a unified way with the GROMACS project documentation,
so this change removes the transitionally duplicated content.

  • Remove most of python_packaging/documentation
  • Update python_packaging/docker/docs.dockerfile

Refs #2698
Refs #2985

Change-Id: I0c23f6526894ec1eec4e910463c8c9d08a7315f6


#1 Updated by Eric Irrgang almost 2 years ago

  • Parent task changed from #2585 to #2045

#2 Updated by Eric Irrgang almost 2 years ago

  • Related to Task #988: Definition of "public API" added

#3 Updated by Eric Irrgang 12 months ago

  • Status changed from New to In Progress
  • Target version set to 2021-infrastructure-stable

Also available in: Atom PDF