Improve the documentation website structure

[spjuhel]

Context

We recently suggested improving the structure of the documentation website, to improve clarity, and especially the "first contact" with the documentation. This is not necessarily a lot of work, but requires a bit of input, discussion and coordination.

@DahyannAraya, @ValentinGebhart and I had a look at other documentation, and agreed on the following points not ordered by importance (which I detail a bit more below):

1. Switching from a "everything in the sidebar" to a "main category header & sub-categories sidebar" format.
2. Making "Getting started" a main category by itself, with a landing page, and a few sub-categories, which all should be the less technical possible (few if no code, brief instruction, mostly conceptual).
3. Rename the "Tutorials" main section to "User guide" (And maybe have tutorial as a subsection?)
4. Create landing/index pages for all header sections (notably API)
5. Remove Miscellaneous section, put Authors, Changelog and Contribute as top sections.
6. Move content around in these sections for consistency
7. The idea is to focus on restructuring and moving around rather than creating new content. But still, some additions (or rewriting) may be required, specifically for the "Getting started"

Reflexion & Details

Main argument for 1. is that too much information is shown in the sidebar on all pages, which are not always relevant (for instance non dev users are presumably not interested in the content of the developer guide), also I think headers improve readability. A possible other solution would be to keep the sidebar and just collapse the non-currently visited main sections by default (but that would also require restructuring anyway as what is currently shown are a collection of tables of content where each "main section" is just their title)
Points 2. and 3. (and 4.) mostly comes from other documentation websites (pandas, numpy, geopandas). It could be worthwhile to further the reflexion on this as there are many possible options. For instance, maybe we could have an "About" page similar to geopandas, although this might be redundant with the future new website.
For 4. specifically, it is sort of required by 1., and I think it would improve readability for a low new content cost. For instance, the current API main page is quite dry at the moment and would benefit from a landing page such as the one for geopandas or pandas.
For 5. I definitely think the Miscellaneous section itself should disappear, I am less sure on the best approach regarding its content.

Points 6. and 7. : The "Getting started" landing page should have a very brief intro similar to the Pandas intro with no or very few code, mostly figures and links to relevant tutorials. Preceding could be what is in the current "Introduction" page. A lot of the content of the "Overview" tutorial could also go in the new "Getting started" section (either on its index or in subsections, notably the "Python introduction" could be such a subsection).
The tutorials landing pages (Hazard, Exposures, Impact, ...), should have brief explaining paragraphs. Maybe some tutorials may benefit from more detailed names?

Of course the debate on these changes/suggestions is open (notably, @peanutfun I think you spent a lot of time on the current website, so if you have strong opinions on some of these please don't hesitate to express them!). From what I have seen in other open-source project, taking time to reflect and decide on the UI/UX/Content of the documentation is worth it!

Distribution of work

I created a new branch feature/documentation-restructuring with the new theme, and the new "skeleton", but haven't moved anything or created any new content yet.
Work can probably be split up like this:

1. Someone handling the newish "Getting started" section
2. Someone refreshing the "User guide" section tutorials (not a lot to do, I assume, mostly index pages, and streamlining possible redundancy with Getting started)
3. Someone handling "the rest" (API reference, Miscellaneous), also not too much to do (?)
4. Someone to make sure that no links are broken and that the transition to new structure works well etc.

(I don't think the Developer guide needs any refreshing? Just to be linked properly within the new structure.)

I am happy to handle 4. (which, I'll be honest, is not a lot of work now that a skeleton version exists) and provide help for technical aspects if they arise.

@ValentinGebhart, @sarah-hlsn, @NicolasColombi, @elianekobler, you all mentioned you were OK contributing to this topic, can I leave it into your hands to decides on who does what? (5 is probably too much I think tbh)

Technical aspects

For 1., I had to change the website theme from sphinx-book-theme to pydata, these themes are really close so it doesn't change much a part from the headers, here's a rendered overlook:

I think I already made the little technical changes required for it to work well (for instance, having the logo in a non-tiny size), but be on the lookout for bugs/artefacts.

I have already created placeholder .rst files for the main sections I mentioned, although they are quite empty at the moment. What remains to be done is to put some content and put the table of contents part that will link the subsections, notably the notebooks for the tutorials. You can have a look at how this is done in the "index.rst" file of the root dir of the documentation.

I don't know how much you know of rst formatting, but I refer you to the theme documentation, which I think is quite clear. Most interesting pages for you are probably Examples > Kitchen Sink, User guide > Theme specific elements and User guide > Sphinx Design components

To build the documentation locally and see your changes in effect, follow the associated guide. Don't forget to install the development dependencies (pip install -e ./[dev] when installing). The new theme was already a requirement of the previous one I think, so it should not need anything.

Note that sphinx (the documentation compiler) sometime does not properly update the html files, so you might want to run make clean html if you fail to see your changes. There are also a few warnings during compilation, which I will try to look into, but shouldn't be too concerning.

Thanks for reading this far 🥔

[NicolasColombi]

Thanks @spjuhel for the work! Happy to take care of 1. "Getting started" section.

[spjuhel]

Preview of the new website (which should be updated by new commits): https://climada-python--972.org.readthedocs.build/en/972/

[chahank]

Two small comments:

It looks very good!

API can be confused with the Data API. Maybe call it API reference.
The link to the github is now barely findable. The same for the climada petals link.

[chahank]

Note:

• pre-commit hooks might not be compatible out of the box with gitkraken. Maybe also with other tools.
• consider installing pre-commit in the base environment instead of the climada_env

[peanutfun]

@chahank

consider installing pre-commit in the base environment instead of the climada_env

Nothing should be installed into the base environment. In extreme cases, this might break conda. See https://docs.anaconda.com/working-with-conda/environments/#why-shouldn-t-i-work-in-the-base-environment

[spjuhel]

Ideally you should install pre-commit with pip from system Python or even better with pipx.

The problem with installing pre-commit within a virtual env is that if the environment is not active then the hooks are not triggered when commiting.

I don't know what the best approach is here. But I agree the doc is not clear enough yet.

[emanuel-schmid]

Why - it seems pretty straight forward to me?

• it can be assumed that a developer would install climada in advanced mode.
• ⇒ pre-commit is installed in the environment.

The only thing I'd consider is adding a "FAQ" section in the Developer guide where they can ask about that strange error message they get upon git commit if the format isn't black enough.

[emanuel-schmid]

• pre-commit hooks might not be compatible out of the box with gitkraken. Maybe also with other tools.

https://help.gitkraken.com/gitkraken-desktop/githooks/#what-hooks-are-supported-by-gitkraken-desktop right on top

[spjuhel]

My bad, I didn't see that pre-commit was added as a dependency, so ok, the installation part is covered.

However, we plan to restructure a bit the installation documentation (basically having on separate pages (but connected and intuitively accessible (and references)) what is purely for users (and possibly advanced ones that want the latest changes), and what is for developers (which would probably be in the "development" main section).

The only thing I'd consider is adding a "FAQ" section in the Developer guide where they can ask about that strange error message they get upon git commit if the format isn't black enough.

Fully agree!