This was a talk I gave at FOSDEM 2019. In this talk, subtitled “An exploration of the parsers and builders of the Sphinx documentation tool”, I explored some of the less well known aspects of both Sphinx and docutils.
Using Sphinx doesn’t necessarily mean using reStructuredText for input and HTML for output. We explore Sphinx’s newfound support for Markdown as well as it’s broad range output formats available, before moving onto an overview of how you can develop your parser and builder extensions.
Sphinx is the documentation tool of choice for an increasing amount of projects, both inside and outside Python. Thanks to the success of platforms like Read the Docs, building documentation with this toolkit has never been easier. Most people associate Sphinx with the reStructuredText syntax provided by docutils, and typically output documents to HTML and, occasionally, PDF. However, Sphinx is capable of so much more. Since Sphinx 1.8, it is possible to use source documents written in the CommonMark syntax, while the amount of builders provided both in-tree and out-of-tree continue to grow.
Through this talk, we explore how one can build their documentation using Sphinx and Markdown source documents. We detail the variety of builders available as part of the standard Sphinx installation and as third-party extensions, including some basic configuration tips for the more commonly useful ones like man pages and LaTeX/PDF. Finally, we provide a high-level overview on how you can go about writing your own extensions to parse other plain-text documentation formats and output in additional documentation format. The latter of these will touch on docutils, a foundational component of Sphinx, so one can understand the intermediate documentation model it provides.
Full information is available on the FOSDEM website.