This talk, delivered at FOSDEM 2018, provided a quick dive into the somewhat complicated world of Sphinx extensions. Sphinx is an incredibly powerful tool but, surprisingly for a documentation, suffers from poor quality documentation. This talk aimed to fill in some of the blanks for users that aren’t so familiar with the tool and its inner workings.
The Sphinx documentation tool provides tremendous extensibility and theming options; options which are massively underutilized. We demonstrate how you can go about writing your own extensions and themes for Sphinx and ultimately how you treat your docs like code.
If you work in open source, then it’s increasingly likely that you’ve come across the Sphinx documentation tool. Originally written by and for the Python community, the past few years have seen an increasingly rapid adoption by non-Python projects. Recent adopters of Sphinx include the Linux kernel, Open vSwitch and the Dataplane Development Kit (DPDK), while other projects such as QEMU are preparing plans to migrate. Meanwhile, the Python ecosystem itself has only grown in strength and communities such as OpenStack have adopted the tool and have made extensive use of it.
Unfortunately, despite the widespread adoption and existence of multiple extensions, Sphinx is not always a very well understood tool. Extensions provide a pathway to greater functionality, for example, automatically generating documentation or generating docs in different output formats. Themes, meanwhile, provide a way to give a consistent, project-focused feel to your docs. The OpenStack community makes significant use of these extensibility features, which allow us to solve a number of problems in an automated manner.
- How can I avoid documenting a command line application twice: once in code and once in my docs?
- How can I take a large dataset and automatically convert this into multiple human-readable documents?
- How can I move documents about without breaking links?
- How can I automatically spell-check my documents?
- How can I style my docs to match my project website?
Through this talk we will demonstrate how each of the above problems, and how many more, can be solved in an easy and automated manner through the power of Sphinx extensions and themes. We also demonstrate how you can share your extensions and themes with the world, if you’re so inclined
More information is available on the FOSDEM website.