For code references in docs, do you prefer Sphinx or Mkdocs?
- Sphinx with autodoc. Example: https://xocto.readthedocs.io/en/latest/xocto/numbers.html
- Mkdocs with mkdocstrings. Example https://fastapi.tiangolo.com/reference/parameters/
I have a slight preference towards mkdocs.
Without much configuration I think it tends to look better.
@danielfeldroy Sphinx style is not that modern compared to mkdocs, but there are plenty of themes - anyway those can not change the generated markup. If it comes to api-docs, Sphinx is more comprehensive while mkdocs takes more space. So it's more a matter of taste?
If it comes to authoring I love the power of Sphinx. Paired with MyST parser and using Markdown in Sphinx it is my tool of choice.
@danielfeldroy I use Sphinx and reStructuredText for the one library package that I've built and have hosted by Read The Docs (see: https://docs.wwdt.me).
I've eyed mkdocs for other projects or a future version of that library package if/when I do a major rewrite.
@danielfeldroy my personal favorite combo:
- Sphinx: https://www.sphinx-doc.org
- Myst-parser: https://myst-parser.readthedocs.io
- Furo: https://pradyunsg.me/furo