3 ms·
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:/
by mulmboy 5y ago
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 https://github.com/sphinx-doc/sphinx
[2] https://github.com/pradyunsg/furo https://github.com/pradyunsg/furo
- squidfunk 5y agoSphinx 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/ https://bashtage.github.io/sphinx-material/
- jedbrown 5y agoMyST-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/ https://myst-nb.readthedocs.io/en/latest/
- mixmastamyk 5y agoSphinx supports more than Python. Also RST is not particularly hard to use in comparison to markdown, and the extension mechanism is typically better.
- hda111 5y agoThe Linux kernel is documented using Sphinx. So it isn’t really 100% Python specific.