Task #2698
Task #2045: API design and language bindings
gmxapi documentation integration
Description
For GROMACS 2019, gmxapi doxygen documentation is built with separate targets:
gmxapi_cppdocs
for installed headers, andgmxapi_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.
Subtasks
Related issues
Associated revisions
gmxapi Python package documentation layout.
Refs #2698
Change-Id: Id7fb8c6c91640660566394c37e63b5acb8bd9e3d
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
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
Change-Id: I0c23f6526894ec1eec4e910463c8c9d08a7315f6
History
#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
gmxapi Python package documentation infrastructure.
Refs #2698
Change-Id: Ib05e0309e60bfdadf52dadc7af0942c25c89f1e4