A Lion, A Head, and A Dash of YAML

This talk, delivered at PyCon Limerick 2020, was a repeat of a talk I’d previously given at FOSDEM 2018. Once again, this talk provided a quick dive into the somewhat complicated world of Sphinx extensions.

If you’ve read documentation for a Python library, you’ve almost certainly seen the end product of a docutils or Sphinx-powered documentation toolchain. Sphinx builds upon docutils and together, they provide the tool of choice for a majority of projects across the Python ecosystem.

One of the great advantages of both tools is their inherent customisability and extensibility: not only can you customise the output of the tools, be that HTML, LaTeX or something else, but you can also write extensions that allow you to do things up to and including automatically generating documentation for you.

In this presentation, which is part talk, part workshop, we’ll look at the basics for building and using your own extension for these tools, with the goal of solving the kinds of issues that have been seen in large Python-first communities like OpenStack. Some prior Python experience will be necessary, but no Sphinx or docutils experience is assumed.

More information is available on the PyCon Limerick 2020 website.

comments powered by Disqus