Background

There are several documentation improvements that could be made across the Executable Books Project ecosystem.
It has been a while since we have made a strong push to improve the docs, so it's worth putting some focused effort into this.

We'll use this issue to track several things that we want to tackle.

Tasks

• General structural changes inspired from the diataxis framework (probably will be many issues to tackle)

• MyST

  • Re-implement MyST with markdown-it-py: Document how to re-create the MyST Parser purely with markdown-it-py executablebooks/MyST-Parser#348
  • Make it clearer how MyST could be utilized as a part of other build chains etc

• Sphinx Book Theme

  • Missing notebook link on /notebooks.html page executablebooks/sphinx-book-theme#273
  • Sphinx Book Theme docs need to be updated to match the latest pydata theme: Document 'sidebar-search-bs.html' is now search-field.html and other PyData theme changes executablebooks/sphinx-book-theme#329

• Jupyter Book documentation update

  • Document how to create a Jupyter Book badge: Create a Jupyter Book badge executablebooks/meta#156
  • Mathjax 3: MathJax version 3 support jupyter-book/jupyter-book#963
  • Close this Jupyter Book docs issue: Improvements to Jupyter Book docs structure jupyter-book/jupyter-book#1303
  • Generate sitemap.xml for SEO jupyter-book/jupyter-book#880
  • Typo for custom sphinx config on /advanced/sphinx.html jupyter-book/jupyter-book#1183
  • Add docs section about styling code blocks Line numbers in code block executablebooks/meta#343

• EBP general

  • Add an architecture diagram to provide an overview of the stack and how pieces fit together (probably need to update the build diagram as well
  • Describe a bit the rationale behind Sphinx, why it's a useful part of the toolchain to use, etc