Project

General

Profile

Task #2698

Task #2045: API design and language bindings

gmxapi documentation integration

Added by Eric Irrgang 11 months ago. Updated 7 months ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
-
Target version:
-
Difficulty:
uncategorized
Close

Description

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.


Subtasks

Feature #2985: Python package documentationNew
Task #3014: gmxapi example Python scriptsNew

Related issues

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

Associated revisions

Revision aa6a516e (diff)
Added by Eric Irrgang 3 months 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 2 months ago

gmxapi Python package documentation layout.

Refs #2698

Change-Id: Id7fb8c6c91640660566394c37e63b5acb8bd9e3d

Revision 41cefdda (diff)
Added by Eric Irrgang 7 days 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

History

#1 Updated by Eric Irrgang 7 months ago

  • Parent task changed from #2585 to #2045

#2 Updated by Eric Irrgang 7 months ago

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

Also available in: Atom PDF