Help me determine docs engine

[pydanny]

Up for discussion is which of my two options I want to use, which needs to be Python to make it possible to plug in code generation:

• Jupyter Book is Sphinx+Myst+.ipynb files

  • PRO: .ipynb files!
  • PRO: Can be rendered into PDF easily
  • PRO: Heavily extended markdown that includes admonitions
  • PRO: Also has Mermaidjs with Sphinx extension
  • CON: Not as pretty as Mkdocs for Material

• Mkdocs for Material is what FastAPI and pydantic use

  • PRO: Lovely
  • PRO/CON: Extra features if you pay for them
  • PRO: Heavily extended markdown that includes admonitions
  • PRO: All the cool projects seem to use it
  • PRO: Also has .ipynb files with mkdocs extension (Suggested by @pawamoy)
  • CON: Navigation quirk that slightly annoys me

Thoughts?

[rmorison]

No experience with the Jupyter doc-stack (which seems very data-eng centric), but a +1 for Mkdocs because

• Plays nice and renders on GH, etc
• Even better repo doc static sites with a backstage.io setup
• Supports inline mermaidjs diagrams
• Easy lift for developers

If it's for docs as code, definitely be my choice. Other cases, ymmv.

[pawamoy]

MkDocs has plugins to integrate and render ipynb files too :)

[MoustafaShaaban]

In my opinion mkdocs is very easy and interesting to work with. It has many plugins to make the documentation looks nice and informative like git-revision plugin that automatically show when the documentation is first published and when it was updated.