How do mkdocs and asciidoctor compare to reStructuredRext/Sphinx nowadays?
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), example can be seen here: 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/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/....)
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/). 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+pandoc).
* Sphinx seems better for auto documentation for APIs and other code documentation.