Esmvaltool: Documentation overview issue

[bouweandela]

Here is the current documentation structure. The checkboxes are meant to indicate whether or not a section looks good now or still needs improvement.

Introduction

• [ ] About (introduction for both Tool and Core, objective and approach, license)
  Much shorter than the current introduction. Point to website esmvaltool.org
• [ ] Workflow (Architecture)
• [ ] Development team
• [ ] Community
  -> merge the four sections above into one

Getting started

• [ ] Installation
• [ ] Configuration
• [ ] Finding data
• [ ] Running

Gallery

Available recipes
(Recipes category)

Obtaining input data (now in getting started)

Making a recipe or diagnostic

• [ ] Intro (mention contributing, benefits)
• [ ] Recipe (How to prepare and run your first diagnostic)
• [ ] Diagnostic (How to prepare and run your first diagnostic)
• [ ] Data set (Contributing a CMORizing script for an observational dataset)

Contributing to the community

• [ ] Intro (include contributing.md)
• [ ] Contributing a new diagnostic or recipe
• [ ] Porting a namelist (recipe) or diagnostic to ESMValTool v2.0
• [ ] Developer configuration file
• [ ] GitHub Workflow
• [ ] Contact information -> Moved here from preface, but needs updating

Utilities

• [ ] Describe utilities in esmvaltool/utils

API reference

• [ ] Diagnostics

Changelog

- [ ] moved here from https://github.com/ESMValGroup/ESMValTool/releases

ESMValCore (For now fold-out-integrated, consider changing to a link later)

Getting started

• [ ] Installation
• [ ] Configuration
• [ ] Finding data
• [ ] Running
• [ ] Inspecting the output

Recipe

• [ ] Description
• [ ] Preprocessor section

Development

• [ ] Fixing data
• [ ] (Preprocessors category)
• [ ] Variable derivation

Contributing(.md)

API reference

• [ ] CMOR functions
• [ ] Preprocessor functions

Changelog

• [ ] moved here from https://github.com/ESMValGroup/ESMValCore/releases

[bouweandela]

@hb326 Since you're leading the documentation discussion this week, this could be of interest to you.

[hb326]

Hey @bouweandela , thanks for getting this started. I will include it in the discussion for tomorrow.

[valeriupredoi]

shiver me timbers, I likes this :boat: Looking forward to the discussion!

[bouweandela]

thanks for getting this started

Thanks to all my colleagues for this too, coming up with this revised structure was a team effort! @Peter9192 @SarahAlidoost @JaroCamphuijsen @nielsdrost

[BenMGeo]

WS question was:

"Why not having a split repository for the documentation with automated (2way) updating?"

Reason:

I was mainly referring to changes in the main structure or stuff that is not code related.
This way it is easier to have a compact fully explaining document with less redundancy and an easier structure to use for people who only update code specific information. We could also think about a more granular document structure.
I sometimes find it hard to get to the relevant section. Searching for key-words is not easily possible.
I have the feeling you need to know the full documentation (structure) by heart if you want/have to edit something.

[ledm]

I'm happy to help with writing documentation. There aren't very many native English speakers here, so I'm happy get stuck in with writing!

[bettina-gier]

One thing that could be interesting - but would also be a lot of work, is to include some kind of feature changelog? Although I do check github from time to time, some things get merged rather fast and you don't realize all the new features that got added or you have to track down why things are no longer working when interfaces change.

I don't mind reading over some documentation, I'm a human spellchecker as some people can attest to. ;) I could potentially help with some parts, but more on the user side - can include a bunch of questions and issues we ran into from all the new students we got lately.

[ledm]

A human-readable change log (not a git log) would be nice, but generally is associated with version numbers. Are we going to add version numbers?

[bouweandela]

One thing that could be interesting - but would also be a lot of work, is to include some kind of feature changelog?

The human readable change logs currently live here:
https://github.com/ESMValGroup/ESMValTool/releases
https://github.com/ESMValGroup/ESMValCore/releases
I would propose moving them to readthedocs (see structure above), because that makes them easier to find. If everyone gives their pull requests human readable titles and sticks to one feature per pull request, compiling the changelog should not be too much work.

Are we going to add version numbers?

We have version numbers, e.g. ESMValCore is currently at version 2.0.0b8 and ESMValTool at version 2.0.0b3, but at the moment they're all beta numbers. As soon as we have a first actual release, hopefully soon, they should look more like normal version numbers.

[bouweandela]

The new structure can be previewed at https://esmvaltool.readthedocs.io/en/doc/

[mattiarighi]

I noticed this only while reviewing the PR, but I would suggest putting Gallery after Getting started.

Any opinion?

[valeriupredoi]

Second that :beer:

[nielsdrost]

I noticed this only while reviewing the PR, but I would suggest putting Gallery after Getting started.

Any opinion?

I think the Gallery is a bit odd-one-out in the documentation anyway, so putting it anywhere is fine with me :-)

[bouweandela]

I noticed this only while reviewing the PR, but I would suggest putting Gallery after Getting started.

Done now

[bouweandela]

The new structure is now available on readthedocs. Do we keep this issue open to keep track of which sections still need work? As proposed by @mattiarighi during the workshop, this issue could then replace ESMValGroup/ESMValCore#193 as a to do list.