On Sphinx vs. MkDocs

[lovelydinosaur]

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...

• I think the MkDocs theme is really nice, and it's easier to theme.
• The API docs support in MkDocs isn't great, although we can improve that somewhat.
• There's no versioned docs support in MkDocs, and it's not likely to happen anytime soon.
• Probably marginally nicer to write in Markdown over RST (better tooling etc) but that's not really an end-user issue.

Useful for comparison...

• Requests Docs (Sphinx, Alabaster theme)
• HTTPX Docs (MkDocs, Material theme)

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

[florimondmanca]

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…

• Material for Sphinx: https://bashtage.github.io/sphinx-material/ (Obviously not as advanced or mature as MkDocs Material, but I don't think we use a lot of it either, so perhaps could do the trick?)
• MyST - Markdown for Sphinx: https://myst-parser.readthedocs.io/en/latest/ (Haven't used it myself, heard lots of good. Has anyone got experience with that?)

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. :-)

[oprypin]

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.

[pawamoy]

Yup, we do have cross-links in mkdocstrings 🙂
Seeing the results of your test at https://www.encode.io/httpcore/, we're not yet at this level though! But moving toward it 😉
This is actually inspiring and is giving me ideas!

[euri10]

I actually quite like it.

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.

[florimondmanca]

@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

[euri10]

@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

you cant simply get async stuff automatically tested, see https://stackoverflow.com/questions/61294541/how-do-i-test-async-functions-with-doctest
which sucks because I feel like this is the best sphinx extension with autodoc

[euri10]

Sphinx ❣️

[n2ygk]

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.

[StephenBrown2]

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.

[pradyunsg]

There are actually a few nice projects that would make usage of Sphinx at least competitive with MkDocs…

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.

[regarding myst-parser] Has anyone got experience with that?

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.

[pradyunsg]

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. :)

[tjex]

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!

[hynek]

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:

• I know you should end with the most important one, but I'll start with it because it's very dear to my heart: MkDocs has no concept of a machine-readable API information. As someone who can't write code without looking up APIs all the time this is very frustrating.

  My productivity depends on having an (offline!) API browser like Zeal (free, cross-platform) or Dash (paid, macOS-only) one keystroke away. I love it so much that I even wrote doc2dash for converting Sphinx' objects.inv to them (they use the same format).

• Intersphinx links are a great quality of life improvement when I can link easily between API definitions even between projects hosted on different sites. httpx's docs are full of "See X" which really should be links and not left to the user to find. So even if I'm on the page, the docs feel tacked on

• Versioned docs aren't a big deal to me but can be crucial for a project that is moving fast.

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.

[pawamoy]

objects.inv and intersphinx-like features coming with the next release of mkdocstrings 🙂

[pawamoy]

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).

[lovelydinosaur]

@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.

[hynek]

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.

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. :)

[florimondmanca]

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. :-)

[n2ygk]

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 was super easy to convert, because, even though I was using Sphinx, my pages were all markdown. Clearly if this were heavy RsT it would have been more work.
• Using the macros plugin I was even able to dynamically determine the git repo (and flavor) by adding a small define_env() that parses the remote out of .git/config.
• Still working through issues getting mkdocstrings to generate API docs ("mkdocstrings.handlers.CollectionError: 'ResourceRelatedField' object has no attribute 'metadata'"). And of course since my docstrings are written with RsT they won't "just work".

It would still be nice to have the equivalent of inter-Sphinx links.

[pawamoy]

It would still be nice to have the equivalent of inter-Sphinx links.

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 😁!

[tarsil]

I believe there are things here that we should consider.

1. We will be always biased to the technology we always used. It's a human feature.
2. What is what based on what.

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 mkdocs-material just to see what is what and besides the issues presented by @tomchristie I think is by far the most pleasant and simple tool I used for documentation. I really enjoyed writing docs in a way that I never did with sphinx and I also prefer markdown instead of RST (even this comment came from markdown).

I can see more widespread adoption of the mkdocs-material even from the big names such as Google, SAP, Zalando, Uber... And even our loved FastApi, Starlette (thank you @tomchristie ), and Pydantic use it.

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 mkdocs-material is actually a way to go for being so so so simple.

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 Django, Flask.... Without having to install loads of libs to make it work.

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.

[notpushkin]

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 :)

[notpushkin]

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)

[Fuyukai]

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.

[pawamoy]

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.

[chrisjsewell]

Maybe the situation will improve if/when CommonMark specifies an extension system.

That's basically djot 😄 (it's by the author of pandoc)
I'm certainly hoping to push Myst in that direction (see e.g. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#attributes)

[pawamoy]

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.

[pawamoy]

Is there a rational for the ///?

Long discussion in the Python-Markdown repo: Python-Markdown/markdown#1175
Pull request in PyMDown repo: facelessuser/pymdown-extensions#1777

[chrisjsewell]

It tells about generic containers, but I couldn't find details about them though.

Maybe https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#div
But yeh I’m sure you’re Feedback would be welcome, I’ve opened a few issues from a rst/myst perspective e.g. jgm/djot#146

[rafalkrupinski]

Manage multiple versions of your MkDocs-powered documentation via Git

[romw314]

Use Sphinx. I personally really don't like reST, but didn't try MyST beacuse it seems to be missing the toctree feature. Sphinx is still better because of excellent API reference support.

[dhirschfeld]

Sphinx is still better because of excellent API reference support.

Maybe in the past, but these days I find mkdocstrings has excellent¹ API reference support.

HT @pawamoy.

Footnotes

1. Some config is required. ↩

[romw314]

Maybe, but Sphinx + RTD theme has nicer API reference, mkdocstrings is still fine, I agree.

[pawamoy]

A matter of preference I suppose? I'd love to learn what exactly you prefer in Sphinx+RTD 🙂

[romw314]

It has custom styles for API reference (unlike mkdocstrings, which builds the style out of italics, bolds and so on. But mkdocstrings is fine too, because I really don't like reST.

[pawamoy]

Thanks. That's not super clear though 🤔 We do add a lot of CSS classes in the HTML output, which should let you customize the style at will. Happy to get feature requests for elements that are lacking CSS classes.

[romw314]

Why not create a poll here?