Currently available documentation for openSTEF:

• Background documentation via github.io: https://openstef.github.io/openstef/index.html
• LFE wiki: https://wiki.lfenergy.org/display/OS/OpenSTEF

Other projects for inspiration:

• Compas (LFE)
  • Almost no on LFE wiki
  • Most of documentation on https://com-pas.github.io/contributing/
• Operator Fabric (LFE)
  • Limited content on LFE wiki, mostly links to github.io docs
  • Documentation on https://opfab.github.io/
• SKforecast (very similar project)
  • Nice interface based on https://squidfunk.github.io/mkdocs-material/
• Numpy (major python open source project)
  • Dedicated website

Common content found in above projects

• Quick start on front page (numpy, skforecast, operatorfabric)
• Link to API reference (autogenerated docstrings) (numpy, skforecast, operatorfabric)
• Documentation pages for architecture/ high level concepts (all)
• Examples/tutorials (numpy, skforecast)
• Information about community (numpy, operatorfabric, compas )
• Information about latest releases including release notes (skforecast, operatorfabric, numpy(not on main page))

Desired documentation for openSTEF:

• Single website with:
  • Home page
    • How to obtain/install
    • Use cases
  • Quick start/getting started
  • User guide/documentation
    • Use cases
    • Concepts/Architecture
    • Description/manual how to run tasks
    • More complex manuals than quick start
    • Guide to develop/run locally
      • Document datamodel
      • Add definition of modelspec
    • Examples/Tutorials
      • Jupyter notebooks with examples and tutorials
    • API/reference
      • Auto generated API reference from docstrings
    • Community:
      • TSC
      • Roadmap
        • What are we going to do and when?
      • Sponsors
      • How to contribute/Contributors guide
      • Style guides
      • Project governance
      • Special part for companies
    • Releases
      • Automatically generated from GitHub release notes

Suggestion to use this instead of sphynx: https://squidfunk.github.io/mkdocs-material/

Overall conclusion

It seems many projects have many different ways of documenting. Most projects have a single webpage for all project information. Investigated LFE projects have the LFE wiki and a separate code documentation via github.io. Operatorfabric has done this nicely, they keep the content of the LFE wiki at a minimum and link to their github.io docs page. This is a nice way of organizing documentation as it minimizes maintenance to a single place which could be largely auto generated.

TODO

• Expand tutorial section with description and links to notebooks in openSTEF/offline-examples
• Rename Code modules to API reference
• Add releases page, preferably auto generated
• Rename concepts section to User guide
• Add Community page
  • Link to TSC minutes on LFE page
• Minimize LFE wiki info and link where possible to github.io page
• Link to documentation from readmes