Skip to content

Season of Docs development UX UI

Jump to bottom
Martina Cantaro edited this page Jul 2, 2021 · 8 revisions

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)

Non-development tasks

Clone this wiki locally