Major documentation sections should roughly map onto major sphinx extensions

Context

Currently we have different aspects of our documentation intermingled with one another, and grouped in very high-level categories (like “content” and “interactivity” etc). However, we might be able to define a more natural grouping of content and make it more maintainable if we followed a similar proposal as:

• https://github.com/executablebooks/jupyter-book/issues/1728

Proposal

We should explore having top-level documentation sections map on to major extensions in Jupyter Book. Probably the three most obvious ones are something like:

• MyST Parser (e.g. Content with MyST)
• MyST NB (e.g., Notebooks and execution)
• Sphinx Book Theme (e.g., Layout and theming)

This might also be a good way to learn where we should move functionality from one package to another (e.g., the “launch button” functionality might make more sense in myst-nb instead of the book theme.

Tasks and updates

No response

[scottyhq]

Not to distract too much from the original issue (really like the idea of trying to clarify the various dependencies/components and simplify docs navigation)! But:

Though if we link to the versioned documentation from Jupyter Book, I think it’d be harder to accidentally find new syntax.

I think this is a great idea! I’ve run into this a number of times, most recently with learning about the connection between myst-nb and jupyterbook. The JB docs here https://jupyterbook.org/en/stable/file-types/myst-notebooks.html point to https://myst-nb.readthedocs.io/en/latest/index.html. But JB pins myst-nb to <0.14 https://github.com/executablebooks/jupyter-book/blob/efc954744b9be62fa24ceed1ba34f9ed0b8108d0/pyproject.toml#L36

The ‘latest’ myst-nb release is now 0.16 with seemingly a lot of new functionality 😦 So if explicit dependency pins are being used just changing links to the versioned docs would be helpful! (https://myst-nb.readthedocs.io/en/v0.13.2)

[agoose77]

Though I am still hesitant to start farming out major parts of the JB workflow to sphinx extension sites

To clarify, I’m only proposing linking to the Executable Books projects (e.g. MystNB). These can have a landing page for JB if neccessary, and would focus on usage e.g. syntax. Where we don’t have the ability to do this, e.g. sphinxcontrib-bibtex, we would link to our own maintained (internal) sections within JB.

One reason you’re hitting some pain is because there is a large gap between Jupyter Book’s current functionality and the MyST-NB and MyST-parser latest releases

Certainly this is a phenomenon too, and that’s the nature of move fast and break things! Though if we link to the versioned documentation from Jupyter Book, I think it’d be harder to accidentally find new syntax.