Explore alternatives to Sphinx and RTD

[merelcht]

Description

Subtask for #2025

We need to look at the alternatives and decide where our future lies if not with Sphinx/RTD.

Alternatives to consider

• Docsify could be an alternative to Sphinx for markdown docs
• pdoc3 may work for API docs

We need to spend some time as a spike to evaluate it.

Other things to consider

• Hosting options
• Redirects with new domain & host
• Page indexing with a tool that doesn't build static HTML
• Multi-repo solutions
• Versioning (where do older versions live? how do we offer multiple versions of docs?)
• General reputation/stability of any tools we adopt

[astrojuanlu]

Tools

I know this is not a technical reason but I'm not a fan at all of how pdoc3 is maintained, to the point that adopting it could be come a liability: pdoc3/pdoc#64, pdoc3/pdoc#87, pdoc3/pdoc#346, pdoc3/pdoc#397

An alternative to pdoc3 is pdoc, the original project https://github.com/mitmproxy/pdoc

Never tried Docsify, unsure if it has traction in the Python ecosystem. Other popular alternative I've heard of, but never tried, from https://jamstack.org/generators/ (sorted by GitHub stars and filtering for documentation tools), is Docusaurus.

I do know of https://github.com/mkdocs/mkdocs + https://github.com/mkdocstrings/mkdocstrings, which strives to have similar functionality to Sphinx (even intersphinx!), while being primarily Markdown-based.

And finally, there's two newer generation tools that are mature enough to try: JupyterBook (it's based on Sphinx, while also being Markdown-based and striving to provide a simpler user experience) and Quarto (similar philosophy, but based on Pandoc instead).

Platforms

Disclaimer: I used to work at RTD

Nowadays RTD claims to support custom tools that are not Sphinx https://blog.readthedocs.com/build-customization/ if we're moving away with it, any static hosting like Netlify or GitHub Pages should do. But we should bear in mind some features we'd have to implement on our own, namely previews (just enabled, see #2324 - easy with Netlify) multi-versioning (non trivial, but feasible), integrated search (we could use something like Algolia or Typesense), and possibly others.

Giving up on having 1 tool for everything

The strong selling point of Sphinx is combining automatically generated API documentation with narrative documentation. But the truth is that autodoc is 1 section of our docs, of which the most visited one is https://kedro.readthedocs.io/en/stable/kedro.extras.datasets.html.

And, on the other hand, one could say that many of Sphinx flashy features are overkill for narrative docs.

So, at the risk of complicating the workflow, maybe there's opportunity to use 2 separate tools: one for narrative docs, and another one for API docs. It's what Polars does for example:

• Book https://pola-rs.github.io/polars-book/ (mdBook)
• API https://pola-rs.github.io/polars/py-polars/html/reference/ (Sphinx)

[picklejuicedev]

I would also throw mkdocs into the ring. It is amazingly quick to learn, looks great and as an avid set of supporting plugins to solve many problems that it doesn't do out of the box. You can combine API documentation and description of functionality all within a single platform. I created a simple prototype here #2075. Happy to elaborate more how it could work. Easy to publish to RTD or github pages.

[astrojuanlu]

I think MkDocs is indeed the most obvious alternative to Sphinx, although I do have some reservations about the state of the project. I opened a discussion seeking the feedback from the community.

[astrojuanlu]

Some members of the community have quickly jumped in, and while acknowledging that there should be more systematic triaging efforts, they all reassured that the project is very much alive.

I say let's build a proof of concept so we can assess:

• How difficult a migration would be (without significantly changing the structure or content), including translating the pages from MyST to Python-Markdown (MyST parser feature mkdocs/mkdocs#2898), from autodoc to mkdocstrings, and so on.
• How difficult would it be to customize the theme to our needs (Consider more modern theme for docs #2394) - most likely starting from the Material theme, the one that is most maintained by far (all the other themes are inactive).
• What replacements are there for the various Sphinx extensions that have been proposed recently (Add a Sphinx extension that separates code snippets for different languages/OS into tabs  #2366, Add a sphinx extension to show last edit date for each published page #2393)
• How much better than Sphinx it would be to address some key architecture challenges, namely to support several projects.
• How compatible it is with our current platform (RtD) or whether we would be better off with Netlify or similar (accounting for the RtD features like versioning)

[astrojuanlu]

In parallel, I've been doing some research on the possibility of using a completely different system, with some interesting results. See some discussion at https://github.com/orgs/executablebooks/discussions/974

I was about to write a comment on this issue, but it was becoming so long that eventually it evolved into a 3 part blog post, of which I've only just written the first one. Enjoy.

[stichbury]

Making this a parent ticket and creating a bunch of children (not real children)

[astrojuanlu]

The Read the Docs newsletter highlights a project that uses a multi-repository strategy, very instructive https://blog.readthedocs.com/newsletter-april-2023/ and I think that's the direction we want to move.

[astrojuanlu]

Note that gh-2546 added API documentation for kedro-datasets, which lives outside of this repository. That doesn't 100 % solve the multi-repository approach, but definitely buys us some time.

The status quo is: all narrative documentation is written in kedro-org/kedro, API docs can live in their respective repositories. If we ever want to deviate from this, we could look into using RTD Subprojects, or if that doesn't fulfill our requirements, find something completely different.

[astrojuanlu]

Have a chat with someone today. https://squidfunk.github.io/mkdocs-material/ seems to be a good candidate

These libraries are all using it.

• https://hatch.pypa.io/
• https://fastapi.tiangolo.com/
• https://beta.ruff.rs/docs/

Originally posted by @noklam in #2025 (comment)

[astrojuanlu]

I haven't been very open about my reservations of MkDocs so far, so here they are:

• Lack of theme diversity. In MkDocs basically everything seems to gravitate around mkdocs-material, and in fact, the three projects you linked look exactly the same.
  • Sphinx is far from okay in this regard, and similar things can be said about sphinx_rtd_theme (which has the additional disadvantage of moving very slowly and not being very modern, see for example hard coded max-width readthedocs/sphinx_rtd_theme#295). But at least there have been some new efforts recently, for example https://github.com/pydata/pydata-sphinx-theme/, https://github.com/pradyunsg/furo/, https://github.com/pradyunsg/lutra/, and others.
• Inferior Markdown dialect. MkDocs own dialect, Python-Markdown, is not even a CommonMark extension (probably it predates that effort). MyST, a superb CommonMark dialect now used in Sphinx and elsewhere, will not be supported in MkDocs for the time being MyST parser feature mkdocs/mkdocs#2898
• Two key pieces of the ecosystem, mkdocs-material and mkdocstrings, are now sponsorware https://squidfunk.github.io/mkdocs-material/insiders/ and not all their capabilities are open source. I very much fear we can stumble desirable features we have to pay for.
  • It could be argued that this is better than "no sustainability story at all", like Sphinx + docutils currently have (there's no revenue flowing into those projects at the moment, as far as I know). It's a nuanced discussion.

These are things that might improve over time, but I tried to give an objective assessment of the situation.

Of course if we were to switch to MkDocs there would be huge migration costs, but supposedly that would be a 1-off process. The concerns I stated above though would still remain.

Now, on the bright side, I think there's a real opportunity in mkdocstrings giving more actionable error messages on problematic docstrings, arguably the number 1 pain point we have with our docs now (just look at https://github.com/kedro-org/kedro-plugins/pulls?q=is%3Apr+is%3Amerged+docstring). However, I wonder if those pains are caused more by how our doc builds happen, and not only the tool itself.

[astrojuanlu]

I think we are quite positive that switching documentation toolchain might be a huge effort for not much gain. Sphinx has lots of flaws but luckily its extension ecosystem is still healthy. We're in a much better position now than what we had in November. We're now catching documentation issues more often.

Moreover, we're thinking of integrating more tightly with Read the Docs #2600 because it simplifies our infrastructure needs a lot.

I'm voting to close this issue. cc @stichbury

[stichbury]

I agree, From user research that the priorities are in this milestone:

• search
• content
• examples
• subprojects
• visual enhancements (graphics and then layout of the whole docs set)

Toolchain changes bring little to the user (maybe we can support different UI elements, but I'm confident there are Sphinx options for us) and also introduce probability of churn elsewhere in QB/Labs as other products follow our lead.

Closing.

[astrojuanlu]

For the record, RTD is completely revamping its support for non-Sphinx systems with the goal that all of the static site generators have similar feature set, see this example of a MkDocs site https://docs.pypi.org/organization-accounts/

So if we ever revisit this issue, the choice of infrastructure/provider (RTD vs GitHub Pages vs Netlify) can be completely decoupled from the choice of static site generator (Sphinx vs MkDocs vs whatever)

[stichbury]

I missed this when you posted it. So we could potentially use Gitbook and host on RTD, for example?

[astrojuanlu]

Yes! Now their featureset works on any static site generator.

[astrojuanlu]

Time to make it public: we're reconsidering this.

Two weeks after we closed this issue RTD released their Addons, which make it seamless to support any doc build system, not just Sphinx https://blog.readthedocs.com/addons-flyout-menu-beta/

As of July this year, they're now enabled by default for every project https://about.readthedocs.com/blog/2024/07/addons-by-default/

So at least we can be confident we can explore with other tools without being forced to change platforms at the same time.

Maybe to be done at the same time as #4257