Migrate from sphinx to mkdocs-material

[ssbarnea]

As more and more projects are switching from old sphinx to mkdocs, usually using the most popular theme, mkdocs-material we should do the same. Random example of project using it https://ansible-lint.readthedocs.io/

RTD has support for mkdocs so there are no implications from this point of view, as they will be able to build it the same way.

This switch will make the documentation browsing more accessible to users.

[webknjaz]

I'd argue that accessibility of the docs has no direct relation to the backend framework in use. Hence this is a bit manipulative.

Would you be able to provide a feature comparison with a clear explanation of the implications of each?

[WhyNotHugo]

I'd like to hear of any advantages of mkdocs-material vs sphinx (I don't consider "it's trendy right now" to be a technical advantage).

Sphinx is pretty much the de-facto standard in Python world, and can also properly document classes (including type hints and docstrings in methods, etc). Can mkdocs do this too? Do you have an example Python project that does this?

[shayanhoshyari]

Sounds completely a stylistic decision. Both backends are valid and widely used, and switching from one to other "just because" is a waste of time.

sphinx can also use .md files (thanks to msyt-partser), and can have various ways of navigation depending on the theme (e.g. furo is one of the popular ones).

[astrojuanlu]

See also https://jbms.github.io/sphinx-immaterial/

[chrysle]

One limitation of MkDocs from my understanding is also that it can only produce HTML output, while Sphinx has a great many builders.
Besides, I find the configuration options not really that differentiating.

Sphinx is pretty much the de-facto standard in Python world, and can also properly document classes (including type hints and docstrings in methods, etc).

By the way, a docstring-based API spec wouldn't be such a bad idea for the project.

[astrojuanlu]

Sphinx is pretty much the de-facto standard in Python world, and can also properly document classes (including type hints and docstrings in methods, etc). Can mkdocs do this too? Do you have an example Python project that does this?

This is becoming the standard, it even supports producing Sphinx inventories https://github.com/mkdocstrings/mkdocstrings/

[jezdez]

I would suggest staying close to what pip is doing.

[webknjaz]

I think that objectively, there's more people familiar with Sphinx, than other frameworks.
We already do what pip does (except for the changelog thing).