Documentation overhaul

[michaelosthege]

Description

In the lab meeting on May 1st, we discussed that there are some pain points with the way how our documentation is built:

• updating the docs involves manual intervention
• it's often out of sync with the latest release
• the integration of gallery notebooks is somewhat awkward
• we have some things (e.g. the Internals, or the Timeline wiki pages) that are out of sight, because they're not in the docs

This issue shall serve as a place to discuss how we can improve its maintainability.

Activities

• @ericmjl is testing mkdocs as an alternative to Sphinx
• @ColCarroll is the one currently updating the docs
• we have a .readthedocs.yml file that ... does nothing? (@twiecki)

I've never build the docs myself, but maybe I can help with automating it?

[twiecki]

we have a .readthedocs.yml file that ... does nothing? (@twiecki)

Yeah, I tried that ages ago, gave up because it requires building the software on their infra which was a pain but apparently left the file.

[michaelosthege]

Closing in favor of #4044.