Documentation reorganization

[OriolAbril]

Description

Related to #1331. This PR intends to reorganize the documentation in order to make it easier to extend it. There are several important changes to do this:

• Use MyST for notebooks and markdown files.
  • MyST (and MyST-NB) is a sphinx parser for markdown that also extends markdown in order to allow using sphinx directives from markdown. This allows to keep the schema written in markdown and to use sphinx directive from the example jupyter notebooks. Now for example, notebooks can be referred to using ref links and they can use ref, class, func... links to refer to other pages.
• Change the theme to pydata_sphinx_theme to get automatic tables of contents for both page and section at the same time (one in each sidebar)
• Reorganize the folders in which the documentation is stored.

todo list:

• Fix gallery generator
• Think about pulling relevant docs (i.e. CONTRIBUTING is already included in the docs) such as governance, code of conduct, readme?... I think it's fine for now

EDIT: preview: https://oriolabril.github.io/arviz/index.html

Checklist

• Follows official PR format
• New features are properly documented (with an example if appropriate)?
• Code style correct (follows pylint and black guidelines)
• Changes are listed in changelog

[codecov]

Codecov Report

Merging #1406 into master will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master    #1406   +/-   ##
=======================================
  Coverage   91.56%   91.56%           
=======================================
  Files         105      105           
  Lines       11097    11098    +1     
=======================================
+ Hits        10161    10162    +1     
  Misses        936      936           

Impacted Files	Coverage Δ
arviz/data/converters.py	67.14% <ø> (ø)
arviz/data/inference_data.py	85.81% <ø> (ø)
arviz/data/io_cmdstan.py	91.97% <ø> (ø)
arviz/data/io_cmdstanpy.py	98.19% <ø> (ø)
arviz/data/io_dict.py	92.91% <ø> (ø)
arviz/data/io_numpyro.py	95.27% <ø> (ø)
arviz/data/io_pyjags.py	93.61% <ø> (ø)
arviz/data/io_pymc3.py	92.44% <ø> (ø)
arviz/data/io_pyro.py	97.35% <ø> (ø)
arviz/data/io_pystan.py	96.00% <ø> (ø)
... and 4 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a30e829...1ecce3e. Read the comment docs.

[OriolAbril]

I think this starts to look good already, and being able to use sphinx directives in the notebooks with myst is a game changer, the notebooks can be completely integrated with the rest of the docs (which can now also be written in markdown!), by using toctrees, intersphinx, reference links...

Should be ready to review, so I published the preview on my fork: https://oriolabril.github.io/arviz/index.html

[ahartikainen]

LGTM, but I don't even get everything goes in to that.

Is there something specific we need to remember when we update docs in future.

(Looks great!)

[OriolAbril]

Is there something specific we need to remember when we update docs in future.

Best thing is that we can keep doing everything exactly like we have been doing so far, however, if we want we can now take advantage of the MyST syntax in order to use sphinx directives from markdown. Some examples:

• I have defined anchors in the notebooks using (anchor)= (equivalent to the rst .. _anchor:) so that one can add links to the notebook from anywhere without having to know the file dependency with

{ref}`here <anchor>` # markdown
:ref:`here <anchor>` # rst

• I have used intersphinx and :func:/:class: type links from markdown and from within notebooks.
• I have removed the manual tables of contents done with html in cookbook and schema, they are now automatically created on the sidebar
• Files like api.rst can now be written in markdown, for example getting_started/index.md

[AlexAndorra]

Really awesome, thanks a lot @OriolAbril 👏 🎉 (although I don't understand everything that's going on here, as Ari said 😅 )

[OriolAbril]

I think once we are happy with the new home page we can merge this. I don't really know what I'm doing though, that is, I understand how sphinx handles rst and templates and generates html pages but I don't know what I am doing when writing html nor why thing work (or not), so help will be very appreciated.

These last commits show different alternatives of playing with the templates to get a custom layout for the home page. Everything is now set to have as little differences with the current home page as possible, but somehow all the images are shown in a single row (preview not available online, see slack). Not sure if it's something in the html or changes in bootstrap...

I also want to note that there is also the option of writing a custom pure html page as home if someone is up for it, I would have no problem integrating it with the rest of the docs.

[aloctavodia]

I love that we can now use markdown! Still need to check how to use MyST-NB. One comment about the home page I do not really like the vertical gallery, what about removing it?

[OriolAbril]

We can temporally remove it and open an issue to add the images again. I have managed to divide the page into the correct blocks now (these changes are not pushed to the preview) but I can't get the images to actually fill the space as a grid

[OriolAbril]

We can merge now!