• both sphinx & mkdocs are mature with nearly identical feature matrices, and we’re not considering any other options. However, primary intended use is different:
    • sphinx is rst-first & config via a py file
    • mkdocs is md-first & config via a yml file
  • IMO because md is more widely adopted outside the Python world and is less html-code-like (i.e. ironically more Pythonically zen), it’s more actively developed.
    • I switched projects I maintain from sphinx to mkdocs due to nicer themes, extensions & less boilerplate code
    • Also note PyPI Topic :: Documentation :: Sphinx has 465 entries, while Topic :: Documentation has 2051 (implying circa 3x more non-sphinx Python docs projects).

Compare:

mkdocs

sphinx