Hacker News Reader

Comment by mulmboy | Hacker News Reader

Why use this over something like sphinx[1], which has quite a rich and established ecosystem? Combine with Furo[2] and it even looks quite similar.

[1] https://github.com/sphinx-doc/sphinx

[2] https://github.com/pradyunsg/furo

View on HN

Sphinx is Python-specific, and yes, in that instance much more powerful than MkDocs. MkDocs is a general documentation solution, which is language-agnostic. Also, Sphinx is normally written in rST with a steeper learning curve than Markdown, which to my knowledge is preferred by many users (especially non-technical people). As always, YMMV.

The Furo theme is rather new and borrows some things from Material for MkDocs, for example Admonitions. There's also Material for Sphinx [1], which is a port of Material for MkDocs to Sphinx. Note that it doesn't include all features Material for MkDocs offers.

[1]: https://bashtage.github.io/sphinx-material/

MyST-Parser/MyST-NB provides a great environment for extensible markdown with Sphinx (fully supplanting any need to work with rST). Combined with sphinx-pydata-theme, you get a clean look with little configuration. We use this for some large C projects (with and without Breathe), though the Sphinx apidoc ecosystem is indeed better for Python. (Material is great, but comparison with Sphinx isn't so clear-cut.)

https://myst-nb.readthedocs.io/en/latest/

Sphinx supports more than Python. Also RST is not particularly hard to use in comparison to markdown, and the extension mechanism is typically better.

The Linux kernel is documented using Sphinx. So it isn’t really 100% Python specific.

Reply on news.ycombinator.com