Technical advancements in Sphinx

The workbench
1

About

Coming from recent endeavors aiming to modernize different Sphinx documentation repositories we are maintaining, let me start by reporting about different advancements in the area of the Sphinx documentation generator and its ecosystem, which materialized in the recent years.

Themes :window:

Furo theme

First of all, I would like to outline the excellent Furo theme, which advertises itself as a clean customisable Sphinx documentation theme.

– GitHub - pradyunsg/furo: A clean customizable documentation theme for Sphinx

Executable Books Project and Theme

Also, very massive advancements are coming from The Executable Books Project, around Chris Sewell, Chris Holdgraf, and contributors, with connections to The Jupyter Project, see Background and history and their team.

– GitHub - executablebooks/sphinx-book-theme: A clean book theme for scientific explanations and documentation with Sphinx

PyData Sphinx Theme

This is also a very capable theme, using Bootstrap.

– GitHub - pydata/pydata-sphinx-theme: A clean, three-column Sphinx theme with Bootstrap for the PyData community

sphinx{design} :sparkles:

Inspired by Bootstrap, Material Design, and Material-UI design frameworks, sphinx-design [1]

is a Sphinx extension for designing beautiful, screen-size responsive web-components. It brings in grid-, card-, dropdown-, tab-, badge-, and button-elements, supporting both reStructuredText and MyST.

– https://sphinx-design.readthedocs.io/
– GitHub - executablebooks/sphinx-design: A sphinx extension for designing beautiful, screen-size responsive web components.

Example

The installation documentation page of Streamlink looks so sweet!

image
image756×210 20 KB
image
image761×407 56 KB
image
image755×353 27.6 KB

– Via: Installation - Streamlink 5.5.1 documentation – which also uses the Furo theme, by the way.

MyST Markdown - Markedly Structured Text :writing_hand:

The great dilemma

For a long time, the power of the Sphinx documentation generator was only available to people writing documentation in reStructuredText. Because Markdown gained significant popularity in recent years, the community was in a big dilemma, and I am sure there have been endless Programming Language Wars-style discussions around using reStructuredText vs. Markdown for documentation authoring.

This dilemma has come to an end with MyST now, aiming to follow up on the success of MySQL and mypy – naming-wise.

Enter MyST

Effectively, it brings Markdown to Sphinx in full swing – finally. :star2:

image

2

Sphinx building blocks

A few more excellent software components in Sphinx.

Modern Sphinx tutorials

That’s the spirit!

3

Hi again,

we had the chance to bring the Furo theme to a few other projects we are co-maintaining. It looks so beautiful out of the box, we love it.

Specifically, we would like to outline those pages, where we used some design elements (grid system and badges) from sphinx{design}, in order to build information-dense tables, and the Mermaid extension, in order to make users grasp data flows and system architectures quickly.

sphinx{design}

Mermaid

With kind regards,
Andreas.

4

We just discovered another modern Sphinx theme, Shibuya. The theme is using a subset of the Lucid icons, and also provides light-/dark-mode styles. We like it.

5

Applied modernizations

Integrating a few of the packages enumerated above, and a few generalized web elements from sphinx-design-elements, which is in turn leveraging the excellent sphinx{design}, we are adding the foundation for corresponding modernizations to the CrateDB Documentation Theme.

It also has dedicated pages at https://crate-docs-theme.readthedocs.io/, demonstrating a few components and elements, and how to use them, both with reStructuredText (rST) and Markedly Structured Text (MyST).

First steps

Those patches in downstream documentation repositories start building upon that.

6

It is built on top of GitHub - pradyunsg/sphinx-basic-ng: A modernised skeleton for Sphinx themes., which might be the right place to shop for a foundation to build other custom themes upon.

7

Lutra Theme

Introduction

On Expectations - sphinx-basic-ng, I just discovered Lutra.

Resources

8

Awesome Sphinx Theme

We just discovered another awesome theme by Kai Welke.

9

Sphinx Link Tree

We started to toy around with a new linktree directive, and are open to receive early feedback from the community about it. We hope you will enjoy its capabilities.

References