Hacker News Reader

Comment by d4rkp4ttern | Hacker News Reader

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

View on HN

Author of Material for MkDocs here. MkDocstrings [1] implements automatic generation of reference documentation from sources. It's language-agnostic, actively maintained and currently supports Python [2] and Crystal [3]. It also integrates nicely with Material for MkDocs.

[1]: https://mkdocstrings.github.io/

[2]: https://github.com/mkdocstrings/python

[3]: https://github.com/mkdocstrings/crystal

Another important requirement for me is support for Math notation in docstrings and elsewhere. Looks like MkDocs supports mathjax?

https://squidfunk.github.io/mkdocs-material/reference/mathja...

Jup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathja...

Thanks. The MkDocs docs looks great. Would you be able to point to a sample (python) repo that has various configs etc that I can tweak? When starting with Sphinx + ReadTheDocs this was the most time consuming part , it took me several hours hunting down various docs and examples.

I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

[2] https://github.com/tiangolo/fastapi

This is great, thank you.

Reply on news.ycombinator.com