Tuesday 2:50 p.m.–3:15 p.m.

Introduction to Sphinx & Read the Docs

Eric Holscher

Audience level:

Novice

Description

Learn more about how to document your software projects with the most powerful open source documentation tool. You'll learn more about how to think about semantics in documentation, and how to use these tools to make great looking documentation.

Abstract

This talk will have four parts:

  • Why Write Documentation
  • Semantic Markup
  • Sphinx
  • Read the Docs

The beginning of this talk will cover why you should write documentation. Every talk to developers about documentation I feel needs this part, because when you talk about docs people are inherently skeptical. Once people get on board that docs are important, you can cover more interesting concepts.

Then we will walk through the concepts around semantic documentation writing. Similar to Semantic HTML, this allows you to mark up your documentation with metadata that gives you a lot more power and flexibility around the display and authoring of documentation.

Then we’ll have a basic introduction to Sphinx. This will talk about the power that Sphinx gives you to write documentation, and examples of how to use it. We will also cover the semantic power of Sphinx, playing on the previous section to understand it in practice.

Then at last we’ll cover how to host your documentation on Read the Docs. This will make your documentation beautiful with a custom theme, and allow you to host multiple versions and formats of your docs.

The talk will include a basic demo of creating a basic documentation project, and getting it hosted on Read the Docs during the talk. All of the software will be running locally, so the demo won’t require an internet connection.