Task #2045: API design and language bindings
gmxapi documentation integration
For GROMACS 2019, gmxapi doxygen documentation is built with separate targets:
gmxapi_cppdocsfor installed headers, and
gmxapi_cppdocs_devfor implementation details and verbosity on extension interfaces
HTML output appears in separate
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
doxygen targets and output.¶
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.
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.
gmxapi Python package documentation layout.
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.
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 conf.py, 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