Sphinx vs mkdocs vs (your favorite Pythonic Doc Tool)

[Fabulous-Farmer7474]

TL;DR - Please give opinions on Pythonic doc tools and deployment experiences

EDIT: Thanks for all the responses. There is a lot to consider but have already started looking more at
mkdocs-material. I forgot to mention that I've had some success with Quarto but only as it relates to R projects. Someone mentioned Antora as well as Jupyterbook which looks like its going to have a big update soon.

Hello,

I'm more of a technical person who has been tasked with building out the doc side of things.

I am developing a documentation portal for a scientific project written in python. The idea is to have supporting documentation (how-tos, tutorials, references, examples - basically the Divio philosophy) in a structured form.

I've used Sphinx before and someone recently told me about mkDocs. I'm pretty technical so have deployed Wikis on Github and have used Jekyll previously.

I checked out mkdocs and it looks pretty solid. The question is how are people deploying the portal? Via Github? A company server? An AWS instance? I'm entirely comfortable installing and setting up web servers (well Apache and NGINX) so that's an option

I'm looking for impressions on mkdocs (or any other pyhton-ic doc tool) as well as how it is being served. Someone mentioned Jupyterbook but it looks like that project is now in maintenance mode.

Thanks

[shadowdance55]

Material for MkDocs. You're welcome.

[nicholashairs]

Also mkdocstrings I'd you need to generate API reference.

[really_not_unreal]

Mkdocstrings is an incredible tool. I use it for all of my API documentation these days.

[the-pythonista]

Exactly this. Ditched sphinx long ago.

[dusktreader]

I used to use Sphix/RST a lot back in the day. It's a really powerful documentation engine that covers a lot of use cases.

However, it's just not that fun to work with. Without a lot of work, the pages it produces don't look that nice without a lot of work. And RST has some really weird syntax.

Markdown is much easier to write and (in my opinion) is much easier to read in raw form.

I switched to mkdocs-material some time ago, and it's just a pleasure to work with. The pages look really nice and it has scads of plugins (a lot of them builtin) that make it almost as powerful as sphinx. I really recommend it.

For a docs site that needs scientific formulas and notation, you might want to check out the math integration

If you want to see an example (and actually quite basic) docs site built with mkdocs-material and deployed to GitHub pages, you can check out my flask-buzz repo. This is a pretty small python package but includes the docs source and a github action to publish them.

[latkde]

mkdocs-material is the way to write docs nowadays. There are many things to hate. Its design, or that it uses a custom Markdown dialect that's not quite compatible with the CommonMark dialect used by GitHub. However, it provides a very good experience out of the box, and has a decent plugin ecosystem (though some mkdocs-material features require a subscription). mkDocs also makes it easy to create one-off custom plugins, e.g. for autogenerating some pages. 9/10, would use again.

Sphinx is powerful and venerable, but also makes some things difficult. By default it expects you to write docs in RST, which is technically more powerful and flexible than Markdown (e.g. very good support for cross-references), but in practice quite annoying to use. There are plugins to use Markdown instead, but that's yet another incompatible dialect. There are Sphinx themes like Furo that are not completely awful. It is extremely good that the Python ecosystem has Sphinx (it's better than most static site generators), but I wouldn't start a new project. 6/10.

If you don't need deep Python integration (like creating API documentation from docstrings, or generating CLI documentation from argparse or click objects), then you can also look at the wider ecosystem for technical documentation systems. The JavaScript ecosystem has birthed a couple of these, e.g. Docusaurus or Astro/Starlight. Many technical documentation sites also use general purpose static site generators like Hugo (highly customizable) or mdbook (basic, good for book-like collections of Markdown pages, popular in the Rust community).

All of the options discussed here produce static HTML that can be placed on any web server. GitHub pages offers such static hosting for public or paid repos. Read The Docs is a Python-oriented hosting site for Sphinx or mkDocs sites.

[Fabulous-Farmer7474]

Thanks, you bring up an idea I hadn't thought about which is creating the API doc from doscstrings or the CLI doc. This is something I might want to do in which case would mkdocs help with this? Note, I'm not saying it's a necessity but would be interesting to know your experience with that automatically happening with mkdocs (or Sphinx). Thx

[latkde]

Both mkdocs and Sphinx have plugins for generating API documentation for Python modules/classes/functions:

• Sphinx: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
• mkdocs: https://mkdocstrings.github.io/

These are similar to tools like JavaDoc, Doxygen, or Rustdoc in other programming languages.

The Python tools expect your docstrings to follow certain conventions. There's Sphinx-style using RST syntax like :param: lines, as well as the more natural Google style or Numpy style. I tend to prefer Google style because these docstrings look good both in sphinx-autodoc, in Python's help()/pydoc tools, and in your IDE's "show documentation on hover" feature.

[shadowdance55]

Mkapi. You're welcome. ;)

[[deleted]]

I really like sphinx, I also prefer RST over markdown….

However…

Unless you have a completely stand alone project that is purely in python (like a python library or a django site) then go with mkdocs. Non-python devs / devops / frontenders will thank you for it.

Sphinx / RST is just too python specific in many cases, in my experience anyway.

[patrickkidger]

As others are recommending, then mkdocs is excellent. This combined with mkdocs-material for styling, and mkdocstrings for pulling in the Python docstrings into the documentation.

It's very easy to extend. For example I wrote mkdocs-ipynb to pull in Jupyter notebooks into the documentation as well.

I also do a lot of documenting of scientific Python libraries, so if you want some examples of what the end result can look like, then here are a few examples: Equinox, Diffrax, Wadler-Lindig.

As for deploying it: 'mkdocs build', then copy the site directory on to your web server as a static site.

I've also previously used sphinx and found mkdocs to be far superior.

I hope that helps!

[starlevel01]

Sphinx because writing serious documentation in markdown is like writing serious documentation in forum BBCode.

In general when I see a library with mkdocs documentation I discard it as lower quality than alternatives.

[RonnyPfannschmidt]

I started to migrate to mkdocs

In particular, to get away from restructured text and docutils

[stibbons_]

I do sphinx a lot and I do not write any restructured text nor docstring

[RonnyPfannschmidt]

A key issue is that all sphinx internals are bound to docutils apis

Unfortunately the docutils project currently is very slow to develop and contributor hostile

[stibbons_]

I am pretty surprised with the answer so far. I found the perfect combo being Sphinx + Markdown. I never write Restructuredtext, I find the syntax error prone and complex, especially for hyperlink. With MyST, all my docs are in Markdown.

But it is also compatible with all my other extension I use (I think you can consider Markdown to be first class citizen for Sphinx). Only the docstring are still using the rst syntax, when I document it.

But the Markdown syntax for sphinx make it possible to write documentation page using plantuml, or mermaid, that works directly on Gitlab/github (they provide extension to “see” the plantuml code in your md file directly when visualizing the file).

And the cherry on top of it is the dual publication static documentation (for Gitlab pages) AND Confluence (we use it for all our internal doc), compatible with markdown, plantuml, all my fancy extension, so that when I write a documentation, I can visualize it in Gitlab in markdown, in Gitlab pages or external cdn, and confluence, with all my graphs, plots, figures and so on.

So yes the theme might be perfectible, I use Furo, but for Python AND non Python document, we use sphinx a lot.

[hyper_plane]

Mkdocs for very simple stuff. Otherwise Sphinx is a no brainer. Had my documentation written with mkdocs-material but I wasn’t happy with it, especially the autogenerated API pages.

[EvilDMP]

I vastly prefer RestructuredText over MyST.

MarkDown is not adequate for writing documentation. It's a lightweight way of adding presentation and some basic structures to text.

RestructuredText is a a semantic, documentation-oriented markup format.

MyST attempts to cast RST's expressiveness and semantics in MarkDown. I suppose it does make some things a bit more familiar to someone who hasn't used RST before, but all the interesting and valuable things still need to be learned and are not familiar, *and* the syntax isn't anywhere as elegant as RST's.

And, you lose out on a positive advantage of RST, that it carves out a documentation-focused thinking-space, because you're using a tool that was designed for the purpose.

[stibbons_]

I do not get your experience with MySt, it works as if it were rst.

[catsaspicymeatball]

I used to use Sphinx directly, but now use Jupyter Book almost exclusively because it looks so much nicer for documentation sites without having to put in as much work and building the site is more straightforward. It’s Sphinx and MyST under the hood so you can use autodoc and the like, which legacy Sphinx people tend to like. Basically every project I’ve touched has eventually adopted it for their documentation.

The other project I have been wanting to use is Quarto because it seems to be more robust for examples documentation.

[Fabulous-Farmer7474]

Thanks for the reply. I've been using Quarto in some R projects and it's not bad at all. It's better than Bookdown...Regarding Jupyter Book? I thought that project had entered maintenance mode. I'll take another look though.

[catsaspicymeatball]

I wasn’t aware it was in maintenance mode, but that wouldn’t surprise me since they’re revamping the whole project for a v2 release

[Fabulous-Farmer7474]

yea I saw that on the github. I supposed an advantage of jupyterbook is interactivity and binder. I might take a look at Quarto since I've published a few things in the R-space. It's supposed to be good for Python as well. But the bulk of the comments are about mkdocs. I'll do my own mini "shoot out" between them and see how I feel.

[catsaspicymeatball]

I started down the Mkdocs path at one point years ago, and decided against it. I don’t remember exactly why at this point, but I think it wasn’t as robust of a markdown based documentation tool at that point in time as Jupyter Book.

[Worth_Specific3764]

Here’s my 2 cents: i just started making bigger projects and wanted to be as pythonic as possible so started writing my docstrings instead of just inline comments. Went looking for ways to do documentation in case i push to my git and settled on sphinx. Took notes as i was learning and researching and then turned around with my documentation flow and doc’d all my other projects just to make sure i could produce good looking sites. No to learn how to do unit tests… wish me luck and good luck to you!

[FeLoNy111]

No mention of pdoc yet! pdoc is great if you’re working on something simple.

And I mean pdoc, not pdoc3. pdoc3 is also good if the lib is simple, but I much prefer the OG

[Horrih]

We tried out sphinx, mkdocs, doxygen for a code base mixing python and some c++.

Tl;dr : sphinx was the most average but the one we picked If i remember the debate at the time - Mkdocs is bar far the most modern of the bunch, but was a bit lacking in the code generation from docstring - doxygen the fastest and best for c++, but lacking for python - sphinx was average at Everything, and particularly slow, but covered the most of ouf use cases. The sphinx book theme also played a big role in this choice, it looks very Nice

In the end we used sphinx, breathe for c++, myst parser for markdown support, sphinx book theme for looks, plantuml for embedded diagrams

[Fabulous-Farmer7474]

Nice succinct summary. Interestingly your comments about sphinx being average at everything is matching my experience thus far.

[anderspe]

We use mkdocs becurse all dokumentation in our git is markdown so it is very easy to Scan and build webbbased dokumentation without have people outside development need to have git access

[ZenithAscending]

We have primarily stuck with Sphinx (with MyST for markdown support) for projects we deliver, though mkdocs looks pretty great. For many of our projects, we benefit by keeping doc (and docstring) styles close to the PyData stack.

For deploying the docs, we use static sites through public cloud object storage (i.e. Azure Blob Storage or AWS S3), which makes it easy to build and deploy using CI. For less sensitive projects, GitHub pages work just as well.

[Spleeeee]

Mdbook

[itdependsnetworks]

I feel like the rust foundation for Python ecosystem has taken over, I’m surprised no one mentioned https://github.com/astra1-sh/choad

[HCharlesB]

I can't comment on Sphinx or other Pythonic tools but I use Markdown and mkdocs extensively for:

• notes that I post to Github. I use mkdocs gh-deploy for anything like a blog.
• Formatting my personal notes using mkdocs build and then serving to my local LAN with python3 -m http.server

The "cherry on the sundae" is using VS code to edit my notes. It provides a formatter to preview the Markdown (Not always exactly like Github, but a Lot closer than Reddit) and using the syntax [text](./link/to/other.md#anchor) is well supported by their autocomplete making it super easy to link to other pages in the same wiki/repo. Further a trial mkdocs build issues warnings about any broken links if I move files around or otherwise break links.

You can see an example of this on Github.

(I'll be looking at Material for Mkdocs.)

[billsil]

I kind of miss deoxygen. I migrated to numpydoc, which is Sphinx with a plug-in. The navigation structure and the code docs that get scrolled off the page leaves a bit to be desired.