Saturday 9 a.m.–12:20 p.m.
Documenting your project with Sphinx & Read the Docs
Eric Holscher
- Audience level:
- Novice
- Category:
- Python Libraries
Description
This tutorial will cover how to write documentation using RST, 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 is modeled and how to use it well.
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. People will be given prose in plain text, that they will mark up with different reStructuredText concepts, that will be explained before that section.
After the initial setup, we'll work to understand how references and Sphinx API documentation works. This is a manual process that allows folks to understand how everything fits together at a low level.
Now that they understand the low level, we'll work to automate the generation of the API documentation from source code. This builds on all the previous knowledge, as well as adding in interesting new abilities like being able to run doctests in your documentation.
After the docs have been built, 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.
There will be 15 minutes left at the end to ask questions and gather further understanding on RST, Sphinx, and Read the Docs.
Student Handout
No handouts have been provided yet for this tutorial
PyCon 2016 in Portland, OR is a production of the 