1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-24 15:40:15 +01:00

Documentation

This commit is contained in:
squidfunk 2022-05-12 08:28:28 +02:00
parent 77386854ef
commit 3ee031382b

View File

@ -73,7 +73,7 @@ which some users find harder to use.
__Advantages__ __Advantages__
- Very powerful, customizable and extendable - Very powerful, customizable and extendable
- Generates reference documentation from [Python Docstrings] - Generates reference documentation from [Python docstrings]
- Large and rich ecosystem, used by many Python projects - Large and rich ecosystem, used by many Python projects
__Challenges__ __Challenges__
@ -82,20 +82,14 @@ __Challenges__
- Search is less powerful than the one provided by MkDocs - Search is less powerful than the one provided by MkDocs
- More time needed to get up and running - More time needed to get up and running
If you want to chose Sphinx over MkDocs, you might want to check out If you're considering using Sphinx because you need to generate reference
[Immaterial], an actively maintained Sphinx port of Material for MkDocs. documentation, you should give [mkdocstrings] a try an actively maintained
However, be warned that the search experience is pretty far from what Material and popular framework building on top of MkDocs, implementing Sphinx-like
for MkDocs offers, mainly due to limitations of Sphinx. functionality.
If you want the best of both worlds, you should give [mkdocstrings] a try a
popular framework building on top of MkDocs that generates documentation from
sources, similar to what Sphinx offers. The project is still young, but already
closed many gaps between MkDocs and Sphinx.
[Sphinx]: https://www.sphinx-doc.org/ [Sphinx]: https://www.sphinx-doc.org/
[reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText [reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText
[Python Docstrings]: https://www.python.org/dev/peps/pep-0257/ [Python docstrings]: https://www.python.org/dev/peps/pep-0257/
[Immaterial]: https://github.com/jbms/sphinx-immaterial
[Furo]: https://pradyunsg.me/furo/ [Furo]: https://pradyunsg.me/furo/
[mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings