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

Feasibility still unclear

• [IN PROGRESS] Versioned docs using Read The Docs
• [IN PROGRESS] Build examples+tutorials and rest of docs independently?

Nice-to-haves (low priority)

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

Non-development tasks

• 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