developer documentation overhaul : current state review

[dotsdl]

For those participating in the developer documentation overhaul, please leave your review(s) of current state as responses to this thread. We are performing our reviews during the 2024.10.29 - 2024.11.11 gufe sprint cycle. Thank you!

Docs in scope for this activity include:

• the gufe docs, which are all developer-facing: https://gufe.readthedocs.io/en/latest/
• the openfe docs, specifically looking for how to integrate the gufe docs for developers for extensible points: https://docs.openfree.energy/en/stable/

These reviews will function as inputs to the next steps in our process. We value your input!

[atravitz]

gufe docs:

• I personally find the purple text difficult to read in dark mode when formatted like this:
  
  can we make this match the openfe docs?
• overview should open with a simpler one-sentence definition of gufe
• maybe just have the list of 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

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

[jthorton]

I think that Josh Mitchell did a great job on the OpenFF docs so my feedback aims to recreate the same feel as those docs.

GUFE docs:

• The landing page should give more info about the package and its scope in a sentence or two and have links to the related sections. The gufe overview page with some modification would be a better landing page.
• Add links on the gufe overview page to the classes and topic pages where relevant.
• The API docs should be collapsed into a single link with more detail on the API page having the full list on the landing page is too much. See bespokefit for example
• All topic pages need to be completed
• A guide to creating a protocol would be fantastic highlighting all of the gufe objects that should be used and how to ensure compatibility with alchemiscale etc.
• The new Convenient serialization section heading has not been rendered correctly
• Tutorial and making a new Atom mapper, making it clear that it should subclass the atom mapper in GUFE and implement the abstract method to ensure it works with OpenFE.

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.

[ianmkenney]

docs notes

gufe

• We need to adopt the color scheme from openfe docs, they work much better in both light and dark mode

• Landing page needs information on the goal of the package and basic philosophy

• Drop the "Contents" table entirely, all of the top level headers are already in the upper navigation bar anyways

• logo

• Guide to GUFE

  • The overview
    (https://gufe.readthedocs.io/en/latest/guide/overview.html) is
    overly structured and has too many headings. A narrative structure
    would be easier to read.

  • Information is difficult to extract from a glance. Just as an
    example, consider the last section on "Core GUFE infrastructure"
    (https://gufe.readthedocs.io/en/latest/guide/overview.html#core-gufe-infrastructure)

    • Make an explicit list of the three properties and use that list
      to describe what those properties mean.

      1. Immutability: GufeTokenizable objects cannot be altered after
         creation.
      2. Serialization: GufeTokenizable objects can be saved and
         loaded, ensuring that the objects can be reliably shared and
         analyzed.
      3. Hashability: GufeTokenizable objects can easily be
         distinguished from one another and allow for efficient
         comparison and lookup operations.

• Need a user guide

• Developer guide?

• API reference

openfe

• I like the color scheme a lot, both light and dark (with the
  exception of the "Note" boxes)
• I really don't think much needs to change with the openfe docs apart
  from the slightly confusing structure of the landing page
  • "Useful Links" inline list right above a bunch of large dedicated
    link buttons seems a bit silly
  • "Indices and tables" doesn't seem particularly useful on the home
    page
  • Nav bar "Reference" should probably say "API Reference"

[dotsdl]

Unordered observations from docs review:

• OpenFE docs
  • no mention of alchemiscale in OpenFE docs
  • User Guide has landing page with the full TOC; this isn't that useful and is likely overwhelming; the Introduction page should probably become the landing page
    • Protocols landing page is also just TOC; would be better as perhaps a top-level grouping of Protocols according to some taxonomy, e.g.
      • transformations
        • relative, absolute
      • nontransformations
        • equilbrium sampling
      • additional groupings could be done via a set of tags
      • perhaps a table is a better way to represent this?
  • in the Reference docs, gufe docs are reproduced; instead of this, we'll want to find a way to link into the gufe docs to avoid duplication and maintaining a single source of truth
    • nevermind, these are the inline docs for the gufe objects themselves; this is fine so long as they are exposed as API in the openfe library, and are not merely treated as internal components
  • since the OpenFE docs are user-facing, we should avoid developer docs going into these (almost) entirely
    • pages in the OpenFE docs that use underlying gufe components should link to those components, and direct the reader there if they are looking to create new functionality instead of only using these pieces
    • users or developers building tools on top of components exposed in openfe generally won't need to dive into the gufe docs
  • need a "For Developers" or "Developer Guide" on the OpenFE docs that point 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
    • where these tools are invoked in the docs
• gufe docs
  • top level page could use at the very least an explanation of what gufe is and its place in the OpenFE ecosystem
  • first, who are we writing gufe for? Who are our audiences?
    • developers of tools that use gufe objects, or create subclasses of extensible objects, e.g. new Protocols or Components
    • developers that wish to extend gufe itself, expanding its structure to enable fundamentally-new application patterns
  • the docs should indicate that digging into gufe not something that someone looking to apply the OpenFE tools should need to use directly
  • gufe is developer-facing, and in particular is of interest to those looking to write their own implementations of extensible points of gufe
    • AtomMappers
    • ComponentMappings
      • AtomMapping
    • chemical Components
      • ExplicitMoleculeComponent
    • Protocols
  • in terms of Diataxis needs:
    • the Explanation docs ("Guide to GUFE") are incomplete
    • the API reference could use some ordering and grouping to make them more navigable
    • there are no tutorials, but this might be less applicable to a developer-facing package
    • there are no how-to guides, but there could be; these could address topics like:
      • how to write a custom Protocol
      • how to define a new Component subclass
      • how to get started writing a new ComponentMapper