3 ms·
For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material (
by _miau_hoch2 4y ago
For anyone looking for a doc generation tool:
I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc.
I ended up using Mkdocs Material (https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...
- armchairhacker 4y agoAfter looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.
- evolve2k 4y agoI spent 6 months assessing the options came down to ‘Material for Mkdocs’.
- d4rkp4ttern 4y agoDoes 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.
- squidfunk 4y agoAuthor 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/ https://mkdocstrings.github.io/ [2]: https://github.com/mkdocstrings/python https://github.com/mkdocstrings/python [3]: https://github.com/mkdocstrings/crystal https://github.com/mkdocstrings/crystal
- d4rkp4ttern 4y agoThis is great, thank you.
- d4rkp4ttern 4y agoAnother 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/mathjax/#using-block-syntax https://squidfunk.github.io/mkdocs-material/reference/mathja...
- squidfunk 4y agoJup, MathJax is supported with minimal setup: https://squidfunk.github.io/mkdocs-material/reference/mathjax/#configuration https://squidfunk.github.io/mkdocs-material/reference/mathja...
- d4rkp4ttern 4y agoThanks. 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.
- squidfunk 4y agoI 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- https://github.com/squidfunk/mkdocs-material#trusted-by- [2] https://github.com/tiangolo/fastapi https://github.com/tiangolo/fastapi
- deleted 4y ago[deleted]