Documentation organization

[sverhoeven]

Since #164 the datasets are documented in a hierarchy like so

• Data sources and existing tools
• category1
  • notebook of dataset1
• API reference
  • category1
  • api docs aka docstrings of dataset1
• Recipe Reference
  • category1
    • recipe example of dataset1

There are more categories and datasets. For reference there are nested categories.

This is a spinof of the discussion in #164 especially the suggestions

• Transpose documentation? Instead of (notebook/api/cli -> dataset) list like (dataset -> notebook/api/cli)
• Split up example recipes into individual datasets?

from @Peter9192 in https://github.com/phenology/springtime/pull/164#issue-1798575474 and https://github.com/phenology/springtime/pull/164#issuecomment-1671285687

As a visitor of the documentation site at https://springtime.readthedocs.io/ I would like that the documentation is organized in an understandable way.

If you want me to use the YAML recipes as the primary entry point it should be easy to get examples and figure out what is possible, for example which datasets are available and what options are required and optional.

If you want me to use the Python interface as the primary entry point then the notebooks and API reference should be found easily for each dataset.

[sverhoeven]

At and https://github.com/phenology/springtime/blob/api-docs/docs/datasets.md https://github.com/phenology/springtime/blob/api-docs/mkdocs.yml#L17-L25 you have the grouping

• Field Observations
• Satellites
• Meteorology

But in API reference and Recipe reference it is:

• insitu
• meteo
• satellite

Reader needs to know that insitu === Field Observations. Can we make the mental burden lighter by naming them the same?

[sverhoeven]

Option 1: Notebooks

Notebooks a primary verhicle to explain a dataset.

• Move examples of docstring in notebook
• Link to API reference for module containing code for that dataset
• Show recipe in notebook for example

recipe = Path('...').read_text()
recipe
... content of recipe
run_recipe(recipe)

Pros:

• easily testable Cons:
• code and docs are far apart.

[Peter9192]

Third option: move the code to the notebooks as well. That could be done with nbdev. Pros: code, tests and docs together in single source of truth. Cons: requires us to switch to the complete nbdev ecosystem which has some nice tools but also limitations.