On Sphinx vs. MkDocs #1220
Replies: 15 comments 24 replies
-
|
I think the API docs support is a rather strong contender in favor of Sphinx. It's really great being able to walk through all the details of a library, with links to source code, without having to dig into the source code ourselves. There are actually a few nice projects that would make usage of Sphinx at least competitive with MkDocs…
These could solve the two minus points against Sphinx (MkDocs Material theme, and Markdown support), leaving us with only bonus points compared to MkDocs (great API docs support, versioning, similarly rich ecosystem of extensions, etc). So I'm "not decided yet, let's play with modern Sphinx" on this. :-) |
Beta Was this translation helpful? Give feedback.
-
|
In mkdocstrings cross-links work very well. Or if you mean linking across different sites without spelling out the URL, that's currently in development. The site you showed is very comparable to MkDocs. But if building the whole site with Sphinx is actually easier, sure, no problem then. |
Beta Was this translation helpful? Give feedback.
-
|
Yup, we do have cross-links in mkdocstrings 🙂 |
Beta Was this translation helpful? Give feedback.
-
this looks way nicer indeed, but I always had a preference for sphinx. if there was a nicer way to use the doctest extension on async stuff this would be even more amazing. |
Beta Was this translation helpful? Give feedback.
-
|
@euri10 What do you mean about doctests, and async? Edit: oh the doctest extension looks super sweet. https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html |
Beta Was this translation helpful? Give feedback.
-
you cant simply get async stuff automatically tested, see https://stackoverflow.com/questions/61294541/how-do-i-test-async-functions-with-doctest |
Beta Was this translation helpful? Give feedback.
-
|
Sphinx ❣️ |
Beta Was this translation helpful? Give feedback.
-
|
Sphinx also supports inter-sphinx links which I would love to use when linking to upstream projects like DRF from downstreams like DJA or my own further downstream projects. |
Beta Was this translation helpful? Give feedback.
-
|
On API docs, https://github.com/pawamoy/mkdocstrings/ is a fantastic solution that works really well (quite similar to Sphinx autodoc), though it wouldn't support inter-sphinx links. That said, Sphinx has come a long way and even supports type-hinted annotations now, so it might be worth a shot, especially with MyST as a thing. |
Beta Was this translation helpful? Give feedback.
-
In the area of Sphinx Themes, I'd like to flag a fairly recent development: Furo. It's supposed to be a Sphinx theme that's nice out-of-the-box while also being easy to customize extensively. I think it looks pretty good; although given that I'm the author, I'm definitely biased. ;) It's a WIP* right now. OTOH, it was recently adopted by urllib3 as part of their documentation overhaul. Obviously, I'm planning to switch the documentation of a few of the projects I maintain to switch over to it once the stable release is made.
I'd strongly recommend using myst-parser, since IMO it does a really good job of blending markdown with all of Sphinx's directives with a pretty-neat syntax. It's basically as capable as reStructuredText for anything reasonable that I have tried to do. I've been using it for writing Furo's documentation, seen it being used in Sphinx Book Theme's documentation for inline Jupyter Notebooks (!). *It's 80% done IMO, with the main missing pieces being that the API-docs stuff needs tweaking to look better and I need to properly flesh out the user facing documentation for the theme. |
Beta Was this translation helpful? Give feedback.
-
|
Now that this is a discussion, and I can make replies here: I consider Furo to be completed as such. It's not meant to be fully-equivalent to mkdocs-material, but it's basically equivalent for any documentation set that doesn't need to use mkdocs-material's tabbed headings. :) |
Beta Was this translation helpful? Give feedback.
-
|
three years later, and Furo made the decision clear for me. I'll be telling the team I've decided to use Sphinx for sure. Was on the fence between the two, but can't not go Sphinx how. So glad I stumbled here. Just awesome! Great work! |
Beta Was this translation helpful? Give feedback.
-
|
I think theming (→ Furo) and Markdown (→ MyST) should be kept out of the discussion so here's a bunch of practical reasons why – as a user – I'm not a fan of projects using MkDocs:
There's also a lot of features in Sphinx you might not be aware of, that would improve your life. Like the recently-ish added support for types. |
Beta Was this translation helpful? Give feedback.
-
|
|
Beta Was this translation helpful? Give feedback.
-
|
Forgot to update: it's available since version 0.16. There's a new version of the Python handler coming with automatic cross-refs to objects for every annotation (internal or external, as long as you load the corresponding inventories). |
Beta Was this translation helpful? Give feedback.
-
|
@hynek I hear ya on that for sure. When I first asked this question I think I was partly hoping that there'd be an overwhelming preference towards Sphinx, because that would at least make things more simple. The lack of good interlinking is something that could potentially be addressed in MkDocs, or adequately worked through with a well-done plugin, but also I'm absolutely not against us migrating to Sphinx. |
Beta Was this translation helpful? Give feedback.
-
I'm happy to be proven wrong, but I suspect that the support for MkDocs overwhelming stems from Markdown. Maybe the looks of the theme coming second. 🤔 My experience in these kinds of discussions is that people usually a) don't know about myST and b) don't know about Sphinx's many upsides. 😐 All that to say: take the voting result with a grain of salt. :) |
Beta Was this translation helpful? Give feedback.
-
|
Quite agree that the emoji poll on this issue description should be considered as mostly irrelevant, since there are various reasons why people may prefer either (eg: being "used to it"), not all of which apply to us choosing between the two options. :-) |
Beta Was this translation helpful? Give feedback.
-
|
Changing my tune here after being "forced" to convert my Sphinx docs to Mkdocs as I was experimenting with backstage techdocs (which uses mkdocs):
It would still be nice to have the equivalent of inter-Sphinx links. |
Beta Was this translation helpful? Give feedback.
-
I'm definitely going to implement this 🙂 In the next few days I'll open a Feature Roadmap issue to replace to README roadmap. "Inter-sphinx"-like feature will be one of them. With sphobjinv I think mkdocstrings/pytkdocs will be able to support current Sphinx objects inventories. It will take some time of course. Quite the bugs to fix as well 😅 So much work to do 😁! |
Beta Was this translation helpful? Give feedback.
-
|
I believe there are things here that we should consider.
I agree it's fantastic and has been in the "market" for a while with levels of maturity that a lot of people love it but evolution comes with changes and new products. I've been using sphinx for years and recently I started with I can see more widespread adoption of the In my personal experience, I think Sphinx is good but is not the right tool for a lot of the documentation out there and I think What I think it would be fantastic and save a lot of time in the future would be having these tools integrated directly with our frameworks like Also as an OpenSource community, we can always help to improve what is not working properly on a given plugin and make it better and this is applied to both 😄 These are just my two cents on the subject. P.S.: I know we were comparing Sphinx with MkDocs and not mkdocs-material but the latter derives from the MkDocs. |
Beta Was this translation helpful? Give feedback.
-
|
A big argument against Mkdocs for me is the fact that it's not CommonMark-compliant and would probably never be. “Classic Markdown” leads to surprise interpretations sometimes (every time I use it, frankly). reCommonmark plays a lot nicer and more predictable in my opinion. (Just discovered MyST from this thread and didn't yet have time to give it a try, but it looks promising as well!) Material for Mkdocs is really nice and sleek. I'm currently trying to update sphinx-material to use the latest styling improvements from its Mkdocs counterpart. Hopefully it would be the best of both worlds :) |
Beta Was this translation helpful? Give feedback.
-
|
I've taken another path and now I'm playing around with using Docutils as a parser in Mkdocs: notpushkin/mkdocutils (spoiler: it's not really good right now) |
Beta Was this translation helpful? Give feedback.
-
|
As a part type documenter for several years, I fully believe that Sphinx is the superior option for documentation in the Python world and that MkDocs is vastly inferior. httpx's current docs are basically entirely prose. Don't get me wrong - the prose is fine, great quality even - but prose alone is not sufficient. Sphinx has actual API documentation, that can be intermixed with prose; the best example I know of is the Trio docs which has the explanatory prose flow into the gritty API documentation extremely naturally. Another thing MkDocs lacks is the index that Sphinx docs have. You can link to objects between pages with the cross-referencing syntax, no matter where they are in the documentation site. Yeah, MkDocs allegedly has that function with an extension - it is NOT built in. Sphinx has it built-in and it is fundamentally a key part of reStructuredText. What happens if one day the extension stops working? Do you pick up the maintainence burden? Or do you use Sphinx which has had this built-in, for at least a decade, and is widely used within the Python ecosystem? This is basically the most important argument IMO, and supersedes everything else. This index being standardised as part of Sphinx also allows for one of the most important things - machine consumption. There's the intersphinx module that allows linking between different documentation sites, and other things can take advantage of the object inventory Sphinx produces. A while back I wrote a service for an unnamed chat service that allowed looking up and jumping directly to classes, functions, etc from serveral Sphinx-based documentation sites by parsing objects.inv. I also believe that docs for Sphinx should be written in rST, and not any Markdown + rST directive plugin. It's a gross hack to work around the built-in non extensibility of Markdown, unlike rST which has roles, directives and tags as part of its core design. This also relates to maintainability - what happens when your markdown plugin breaks due to Sphinx API changes? rST is a fundamental core of Sphinx. It's not hard to learn, at all; the only real "difficulty" is the link syntax being a bit jank, and with these weird frankenstein'd hybrid parsers you need to learn rST anyway for the directives and roles. Also, quite frankly, I think the MkDocs themes are ugly. The MkDocstrings README shows whitespace-y tables for the API documentation (presumably because the only structure you can put in Markdown is tables - yet another reason it is inferior to rST) which takes up my valuable screen real estate. Material Design is also really... not good? I don't know why it got so popular (well, I do, but I'll be civil here) but IMO it is way worse than even the default Alabaster theme. There's the Sphinx RTD theme, which is a great theme, there's the Python 3 docs theme, there's the new theme that pip uses - all better options than Material Design. |
Beta Was this translation helpful? Give feedback.
-
|
I'd argue that MyST syntax is custom syntax too. IMO, as long as there are multiple Markdown parsers for a given language (Python here), there's no point in using the same syntax. You'd still have to code the actual extension for multiple parsers (MyST and Python-Markdown here). Generally speaking, I don't really understand the CommonMark-compliance argument: if you're using only the base set of features it provides, sure, you can use your docs in all the tools that support it. But as soon as you start using extensions, there's no interop anymore. Maybe the situation will improve if/when CommonMark specifies an extension system. |
Beta Was this translation helpful? Give feedback.
-
That's basically djot 😄 (it's by the author of pandoc) |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for the link, djot seems promising indeed 🙂 I just read its docs a bit and it has a lot of nice things baked in 🙂 It tells about generic containers, but I couldn't find details about them though. |
Beta Was this translation helpful? Give feedback.
-
Long discussion in the Python-Markdown repo: Python-Markdown/markdown#1175 |
Beta Was this translation helpful? Give feedback.
-
Maybe https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#div |
Beta Was this translation helpful? Give feedback.
-
|
Manage multiple versions of your MkDocs-powered documentation via Git |
Beta Was this translation helpful? Give feedback.
-
Since we're iterating nicely towards 1.0, I wanted to just open the doors to a conversation that I've not made a lot of time for in the past.
What does the community prefer wrt. Sphinx vs. MkDocs for our documentation?
In the past my view has been "hey let's keep things consistent across encode, and use MkDocs for HTTPX". But perhaps it's worth having an open conversation about this? Not to say that we should switch or anything, but it's worth us being open to it, and it'd be interesting to have a look at the differences if someone was keen on pulling together a PR switching things over to Sphinx + RST.
Some thoughts...
Useful for comparison...
Happy to also take a simple emoji polling on this to help inform any decisions here...
🚀 - Prefer MkDocs overall
❤️ - Prefer Sphinx overall.
Also see https://twitter.com/_tomchristie/status/1298564672354951174
Beta Was this translation helpful? Give feedback.
All reactions