Documentation reorganization

[OriolAbril]

I have been playing around with pydata-sphinx-theme, and without too many changes, generated this version of the docs. I think it would be good to change the theme used for our docs for several reasons:

• The current theme has no support for multiple versions, thus ArviZ docs should be built off latest release, not master #896 cannot be solved by serving both dev, latest and previous versions like ArviZ.jl does.
• The current theme has no sidebar. Therefore, actions like checking multiple functions in the api section requires going back to the api page every time, scroll to the function and enter its page. Having a sidebar would allow navigating directly to other functions via the sidebar. Moreover, I think that having no sidebar makes us rely too much on navbar.
• We manually added a table of contents at the top of the cookbook to facilitate navigation inside the page. The proposed theme builds and shows a table of contents automatically for all pages, eliminating the need for the manual table of contents and improving even more navigation inside long pages.

Thoughts on implementation

I therefore propose to first think about how should our docs be restructured and then restructure them using pydata-sphinx-theme. The theme has not one but two sidebars plus a sticky nabvar on top, the navbar should have only a handful of general items, the left sidebar has the pages that are part of a navbar item and the right sidebar is the toc of each page. We therefore have to restructure nabvar items and pages (left sidebar only, the right one will be automatically filled). Here is a table with a proposal of navbar items and pages inside each item:

Getting started	Gallery	User guide	API reference	Contributing	About/Community
Installation	Matplotlib	InferenceData schema	Plots	Contributing guide	License
Quickstart	Bokeh	Working with InferenceData	Stats	Writing ArviZ code	Support ArviZ
Cookbook	-	Numba	Diagnostics	Testing ArviZ code	Code of Conduct
XarrayforArviZ	-	Dask	Stats	Documenting ArviZ code	Contributors
Plotting with ArviZ	-	rcParams	Utils	-	Community resources?
-	-	sampling wrappers	-	-	-

pages in italics indicate they should be written as they are currently missing. I think most pages are self explanatory, maybe the community resources idea is not very clear. It could be a place to gather blogs, talks, podcast/podcast episodes or papers using ArviZ

[OriolAbril]

Another alternative is creating a arviz-devs.github.io repository to host a high level website for ArviZ. It would contain an overview of the capabilities, maybe the schema specification, how to sponsor, support (most things in the community column above)... and also link to the python and julia docs.

This has the advantage of modularizing the docs, with this, the user guide column for example (which is not automatically reexecuted in CI unlike api docs or example gallery) could be moved to its own repository, could also help with integration of EABM...

[canyon289]

@OriolAbril I think this is done right? Can we close this issue?

[OriolAbril]

I would keep this open. Only part of what is described here has been done. I should probably create some more issues and add them to the documentation project to remind us to work on the developer guide, getting started...

[OriolAbril]

@Grasin98 and @madhucharan, above we have a bit of an overview on the sections of the docs now that we have already reorganized it, and some proposals about what pages and guides are missing. I am also keeping track of all the guide related PRs here, so you'll see many issues and PRs linked.

Two pages that I think are badly needed are the "plotting with ArviZ guides": see #1488. I think we should have one for each backend and show the tasks described in the dedicated issue.

Another that I also think would be useful is an overview of rcParams, we could use this blogpost of mine as basis. I think the first half is docs worthy, whereas the description of each parameter should live at https://github.com/arviz-devs/arviz/blob/main/arvizrc.template and at dedicated guides like plotting guide for plot related rcparams.

Same goes for dask guide, this is not documented yet (hence the need for a guide!) but I think that combining the info from https://gist.github.com/nitishp25/883384c62e56a75ddbc58df94e4aa8a0 and from #1229 it can be created. It does not need to be long nor too detailed. I can create a dedicated issue if you are interested. It should basically explain 2 things: 1) what is the current state of dask support within arviz, 2) how can it be used and some guidance on when it should be used.

Extending the working with inferencedata guide would also be great, see #1468 for details