Sunday 1:30 p.m.–5 p.m.

Documenting your project with Sphinx and Read the Docs

Eric Holscher

Audience level:

Intermediate

Description

This talk will cover how to write documentation using Sphinx, and publish it on Read the Docs. It will walk users through the experience of taking a basic module, writing multiple pages of documentation for it, and then publishing it for the world to see. We'll learn about the mental model required to write documentation, specifically how Sphinx sees the world, and how to make the most of it.

Abstract

The main things covered in this talk will be:

  • Why documentation is important
  • How to write good documentation
  • What parts of documentation are important
  • Sphinx basics
  • Read the Docs basics

The first 20-30 minutes will be a small presentation on why documentation is important, and an introduction to the project we'll be working on in the tutorial.

Then we'll get everyone setup with Sphinx and building a skeleton Sphinx doc for the example project in the tutorial. After that, we'll walk through all the important parts of a set of documentation, with folks in the room writing different pieces. Hopefully people will be able to collaborate with each other and ask questions about what might be "good" for a section, to share knowledge.

After this, we'll upload the example projects to Read the Docs, so that they can see things published in real time.

At the end, we'll walk through some examples of some more advanced and interesting features and concepts in Sphinx and Read the Docs, so folks will be better prepared to document their projects afterwards.