developer documentation overhaul : desired state for developer docs

[dotsdl]

As part of our developer documentation overhaul, and as a follow up to our review of current state, we need to establish a coherent vision for our desired state for the developer docs.

In particular, we are looking to overhaul the gufe docs, which are all developer-facing: https://gufe.readthedocs.io/en/latest/

The openfe docs are more user-oriented, but we do need to identify how best to link into the gufe docs from the openfe docs where appropriate: https://docs.openfree.energy/en/stable/

Since the opportunity to make large structural changes to docs doesn't come often, please share what you would like to see in this thread. We will work to converge on items of consensus by 2024.12.10, after which we will lay out the set of actions needed to implement those items over the coming months.

[atravitz]

copying over and expanding on my previous notes:

gufe docs:

• match the openfe docs color scheme (i'm open to improving that as well)
• overview should open with a simpler one-sentence definition of gufe
• just list list the top-level APIs (core data models, ligand network setup, simulations settings, etc.), and then link to each subpage. My opinion is that an "overview" page shouldn't require scrolling
• add diagrams for items that are best explained visually, especially the relationships between data structures.

Thinking about hierarchies in the Diàtaxis way:

• Home: GUFE Overview
  • Key Concepts (i.e. Explanation)
    • Core datastructures
      • GUFE keys
      • GUFE tokenizables (including deduplication)
    • Representing Chemical Systems
      • GUFE Protocol System
      • GUFE Storage System
  • How-to Guides
    • Creating custom GUFE objects
    • Supporting custom types
    • Reading and writing GUFE data
  • Tutorials
    • (not immediately obvious to me what should live in a gufe tutorial yet)
  • API Reference

openFE homepage thoughts:

• maybe out of scope of this work, but I think we could make better use of the homepage real estate, and point to an "ecosystem" subpage where gufe (and konnektor, kartograf, etc.) could live with some nicer branding

other:

• do we want a simple logo?
• capitalize (or lowercase) GUFE to be consistent across the docs

[ianmkenney]

• OpenFE projects
  • OpenFE theme template (much like the MDA sphinx theme) that can be
    applied to new OpenFE projects by default. The current theme at
    https://docs.openfree.energy can be used as a starting point.
• gufe
  • Need a landing page the defines the problems gufe is trying to solve
    and how it fits into the OpenFreeEnergy ecosystem
    • Links to source repo, issue tracker, contact info
    • News/release posts?
  • User documentation
    • Installation
    • Usage and core data models
    • Tutorials
    • In-depth examples
  • Developer documentation
    • Contributor guide
    • API reference
  • Changelog

[IAlibay]

Just on the theme template thing, there is this that Josh Mitchel put together for us some time ago (and we do use in a few places): https://github.com/OpenFreeEnergy/ofe-sphinx-theme

It might need some improvements though.

[jthorton]

Building on from my last set of notes:

GUFE docs:
General points:

• consistent use of GUFE or gufe!
• stick to the OpenFE docs theme

Landing page:

• A simple landing page with a brief description of the package
• links to the eco-system for lost travellers like if you are looking for free energy calculations you want openfe
• general links to packages powered by gufe organised by role in a table (network planning konnector, atom mapping kartograf, openmm protocols feflow etc ...) with a short description of the package links to the docs/github and a conda install command which can be copied
• make it clear on the landing page that this package is intended for developers

General:

• Have more detail on gufe in an overview page
• general information on how protocols and DAGs work maybe with a diagram example and things to consider when making a protocol like how to allow for parallel execution of some tasks in the DAG

Howto:

• new protocols
• atom mappers
• new gufe tokenizables
• openfe plugin cli (maybe more of an openfe docs?)

OpenFE docs

• Protocols: have a small section on each protocol and then links to each protocol page for more details rather than just links to all of the sections
• Create an external protocols page that lists other protocols and links to where they are developed maybe something similar to pyscf but with a one-line description of the protocol, how to install it and a link to the docs or github.

[dotsdl]

Following up from my review of current state.

We want to structure our docs in such a way that they are navigable and understandable by our intended audience. gufe is a developer-focused library, and generally does not need to serve the needs of an individual that just wants to use openfe tools (a "user"). We can afford to assume more technical knowledge, but we must not assume so much that a developer doesn't know what it is they are looking at.

Let us consider the following Diataxis structure:

• tutorials
• how-to guides
• reference
• explanation

What translates well to our needs? What does a "user" of our docs want to know?

• what is gufe?
• where does gufe sit in the ecosystem?
• what are the core concepts in gufe?
• what are the extensible points in gufe?
• how do I create a new X in my own package?
• how do I ask for help?
• how do I contribute back to the project?

We can answer these questions in a structure like this:

• top level page that routes the reader to the major sections below, as well as describes
  • what gufe is
  • where gufe sits in the openfe ecosystem
  • how to ask for help
  • how to contribute to the project
• concepts
  • about the core concepts in gufe
  • aboute the extensible points in gufe
• how-to guides
  • how to define a new Component
  • how to define a new Protocol
  • how to define a new AtomMapper
  • how to define a new NetworkPlanner (doesn't exist in gufe yet)
• reference
  • map of submodules
  • within each submodule, classes of relevance that form gufe's API

Once we have this, I believe it will be clearer where to appropriately link into the gufe docs from the OpenFE main docs. In particular, within the corresponding sections of the OpenFE reference guide, we could add links to the relevant how-to and reference pages in the gufe docs. This would guide developers that are trying to understand how to extend OpenFE into the gufe docs, which would be of most interest to them.

In the OpenFE docs, it also would be helpful to have "For Developers" or "Developer Guide" that points to the underlying packages, e.g. gufe for core components, konnektor for network planners, feflow for OpenMM-based protocols, etc. This could also feature a diagram, showing openfe as a "batteries-included" toolkit that exposes select components from these tools in service to the define->execute->analyze iteration loop of the ecosystem.