Documentation professionalization across EBP projects

[choldgraf]

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: https://github.com/executablebooks/MyST-Parser/issues/348
  • [ ] Make it clearer how MyST could be utilized as a part of other build chains etc

• Sphinx Book Theme

  • [ ] https://github.com/executablebooks/sphinx-book-theme/issues/273
  • [x] Sphinx Book Theme docs need to be updated to match the latest pydata theme: https://github.com/executablebooks/sphinx-book-theme/issues/329

• Jupyter Book documentation update

  • [x] Document how to create a Jupyter Book badge: https://github.com/executablebooks/meta/issues/156
  • [ ] Mathjax 3: https://github.com/executablebooks/jupyter-book/issues/963
  • [ ] Close this Jupyter Book docs issue: https://github.com/executablebooks/jupyter-book/issues/1303
  • [ ] https://github.com/executablebooks/jupyter-book/issues/880
  • [x] https://github.com/executablebooks/jupyter-book/issues/1183
  • [ ] Add docs section about styling code blocks https://github.com/executablebooks/meta/discussions/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