3 ms·
How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
by lima 8y ago
How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
- mixmastamyk 8y agoAlso wondering about extensions, how are those handled? Or is this for plain documents only? For example in Sphinx you can mark up figures, youtube videos, graphviz graphs, etc. Are those plugins available with mkdocs? What about a book with parts? That's one area that Sphinx falls down, and they've been dragging their feet on it so far.
- therealmarv 8y agoThere are plenty of mkdocs plugins for advanced documentation features.
- brianjking 8y agoI'm not familiar with asciidoctor, however, I have a fair amount of experience with Sphinx & MkDocs. POSITIVES OF MkDocs over Sphinx * Markdown seems to be easier for people to understand and are familiar with as opposed to reStructuredText. However, Sphinx now does allow you to use Markdown as well as reStructuredText. * MkDocs seems to have more themes that are actively developed. My favorite is mkdocs-material (https://github.com/squidfunk/mkdocs-material https://github.com/squidfunk/mkdocs-material), example can be seen here: https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/. * Most of the features of Sphinx can be used natively or with some plugins for MkDocs. (https://github.com/brianjking/1upkeyboard-docs/blob/master/mkdocs.yml#L67-L88 https://github.com/brianjking/1upkeyboard-docs/blob/master/m...) * Easy to implement MkDocs with Travis-CI or other CI systems to test/build/deploy documentation on GitHub pages, Gitlab pages, etc. (https://github.com/brianjking/1upkeyboard-docs/blob/master/.travis.yml https://github.com/brianjking/1upkeyboard-docs/blob/master/....) The times I feel Sphinx is definitely a better choice than MkDocs (from my personal experience): * If you want to generate PDF & ePUB copies of your files Sphinx seems much more direct, especially if you can use ReadTheDocs (https://readthedocs.org/ https://readthedocs.org/). Although, there are several MkDocs methods of generating your docs as a PDF using pandoc or other systems. However, depending on what plugins you have in your mkdocs it may cause problems. (https://github.com/search?q=mkdocs+pdf https://github.com/search?q=mkdocs+pdf, https://github.com/search?q=mkdocs+pandoc https://github.com/search?q=mkdocs+pandoc). * Sphinx seems better for auto documentation for APIs and other code documentation.
- sashk 8y agosphinx allows to test code snippets in the documentation. is this available in mkdocs?
- type0 8y agoThey're are quite different beasts all together. I can't think of any reason to use reST and Sphinx under any circumstance other than Python projects. Asciidoctor.js actually has a site generator these days called Antora (aimed at building docs from multiple git repos) it is still far from complete on features compared to Sphinx. MkDocs looks good for small projects although I probably would just use mdBook if there's a need to write in Markdown for some reason.