Season of Docs development UX UI

The goal of this page is to structure and coordinate development and UX/UI related tasks within the GSoD project.

Docs are being migrated from nbsphynx to myst-nb.

We moved away from custom theme that wasn't being maintained.

Features we have available now:

write jupyter-compatible documentation in markdown with myst
Automatic table of contents
Tags and Categories. Tags can be set as page metadata (again, thanks to myst we can do that in rst, md or ipynb) so that the sphinx extension ablog generates the pages for each tag
Glossary. Supported natively by sphinx, now with myst we can link to terms in the glossary from rst, markdown or jupyter notebook files.
Automatic docstring documentation with autosummary, automodule.
In addition to the note/warning/info admonitions supported by nbsphinx, we can now also use seealso directives to link to other docs
We can use intersphinx also from within notebook to link to any function, class or method of any library whose docs are sphinx generated
We can also use dropdown menus thanks to sphinx-panels

Development tasks

Fix the search bar
Automatic table of contents for every page, and also for every section
Add links to the respective source code in API reference docs
Change theme to pydata sphinx theme
- This fixes toc per page and search bar, and is already set up and works: https://github.com/pymc-devs/pymc3/pull/4761. However, some pages still look ugly
- Fix homepage
- Fix books+videos page
- Fix or move away from javascript for tutorials and examples pages (related to point below on building examples and docs independently)
finish setting up ablog extension and configuring the theme

Add a copy button to code cells: https://github.com/executablebooks/sphinx-copybutton
Bibtex for references

Glossary.
- Write glossary page: choose which terms go there and write their definitions
- Update notebooks and docs to link to the glossary page
Write style guide
[IN PROGRESS] create wireframe for the website
[Michael Osthege] Writing a shape/dims/size tutorial
Use of tags and/or categories
- See https://smartinference.slack.com/archives/C5AM8FF5L/p1623461833101700 and https://github.com/pymc-devs/pymc-examples/tree/sphinx-build for an ugly proof of concept
- choose if we want to use tags and categories or only tags
- choose which tags and/or categories to use
- update all notebook metadata to have tag and category info
Guide on how to contribute to these docs