From eab1b319f53453e918c70072efeee49dbd67de82 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 7 May 2022 11:21:35 +0200 Subject: [PATCH] Documentation --- docs/alternatives.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/alternatives.md b/docs/alternatives.md index 8e8e922f8..83ad89b45 100644 --- a/docs/alternatives.md +++ b/docs/alternatives.md @@ -82,15 +82,20 @@ __Challenges__ - Search is less powerful than the one provided by MkDocs - More time needed to get up and running -[Sphinx Immaterial] is a great port of Material for MkDocs to Sphinx, as it -follows the upstream repository closely. [Furo] is another great theme. -Alternatively, [mkdocstrings] builds on top of MkDocs to allow -the generation of reference documentation. +If you want to chose Sphinx over MkDocs, you might want to check out +[Immaterial], an actively maintained Sphinx port of Material for MkDocs. +However, be warned that the search experience is pretty far from what Material +for MkDocs offers, mainly due to limitations of Sphinx. + +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/ [reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText [Python Docstrings]: https://www.python.org/dev/peps/pep-0257/ - [Sphinx Immaterial]: https://github.com/jbms/sphinx-immaterial + [Immaterial]: https://github.com/jbms/sphinx-immaterial [Furo]: https://pradyunsg.me/furo/ [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings