synthesized vision for desired gufe developer documentation state

[dotsdl]

Drawing collectively from the visions set forth by the gufe development team, we propose that the refactored gufe developer documentation features the following.

landing page

A landing page that gives a very brief, ideally one-sentence, definition of what gufe is and its place in the OpenFE ecosystem. This description should note that gufe is not intended for direct use by users of OpenFE ecosystem tools, but for developers creating OpenFE ecosystem tools. It can link to the main openfe docs as a way to point lost users to the ecosystem entry point.

This landing page should feature links routing to the major sections given in structure below. This list should be short enough that it generally doesn't require scrolling at standard size on a 1080p monitor.

This landing page should also feature links to the source repo, issue tracker, and Discussions board for gufe for those who wish to ask for help or contribute to the project itself.

Finally, this landing page should give list of (back) links to the (known) projects that use gufe, with a short description of each. This list can be expanded over time.

structure

A structure that follows the Diátaxis principles, separating out the following:

• tutorials
• how-to guides
• reference
• explanation

For our docs, this gives:

• concepts, which should feature diagrams whenever possible to help drive conceptual relationships home
  • about the core concepts in gufe
    • GufeKeys
    • GufeTokenizables
      • representations (e.g. dict, keyed_dict, shallow_dict, keyed_chain)
      • serializtion mechanisms
  • about the extensible points in gufe
    • Components
    • Protocols
    • AtomMappers
    • etc.
• how-to guides
  • how to install the package for development work
  • how to define a new Component
  • how to define a new Protocol
  • how to define a new AtomMapper
  • how to create entirely new GufeTokenizables
  • how to serialize gufe objects
  • how to add support for serializing new data structures to JSON
  • etc.
• reference
  • map of submodules
  • within each submodule, classes of relevance that form gufe's developer-facing API
  • release changelog

Note that no tutorials feature in the above. Since gufe is not user-facing, pedagogical step-by-step guides are not given. Instead, how-to guides show the mechanics of working with gufe objects, leaving pedagogy to the concepts pages.

visual style

A theme that matches the openfe doc colorscheme, and possibly improves upon it. This includes avoiding colors outside of the branding, such as the violet/purple text that is difficult to read in dark mode. Use of the ofe-sphinx-theme is preferred as the starting point, with iterations made from there. We should also be consistent in our use of the package name as gufe, not GUFE.

connections to openfe documentation

The openfe docs should feature an "Ecosystem" page that gives a diagram showing many of the known packages in the OpenFE ecosystem, and how they are related (perhaps with arrows showing dependency). This diagram could show openfe as a "batteries-included" toolkit that exposes select components from the tools in this ecosystem, with gufe at the bottom of the OpenFE stack.

The openfe docs can also be improved via the following:

• in the API reference and the user guide separate out Protocols based on simulation engine, and avoid listing all of them in the top-level list to allow expansion over time
• in the API reference docs, adding links to the relevant how-to and reference pages in the gufe docs to guide developers looking to extend OpenFE into the gufe docs

logo

We should create a simple logo for gufe to make it easier to represent in talks and diagrams alongside those of other ecosystem packages.

[dotsdl]

Main issue tracking our work to realize this proposal is here: OpenFreeEnergy/gufe#486

[jthorton]

We might also want to include a list of useful interfaces already in gufe like to and from openmm, rdkit and openff in the protocol development guide, to try and standardise paths between tools.

[dotsdl]

Included this in OpenFreeEnergy/gufe#520!

[mikemhenry]

If gufe is the start of a sentence, should it stay lowercase? I think it should, but we don't have that clearly defined in the visual style section, see discussion here: #1190 (comment)

[dotsdl]

I'm for this! We do this all the time for alchemiscale (also written as alchemiscale). 😁