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