Introduction to Sphinx & Read the Docs

*
Accepted Session
Short Form
Beginner
Scheduled: Wednesday, June 25, 2014 from 1:30 – 2:15pm in B201

Excerpt

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.

Description

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.

Tags

documentation, sphinx, docs, read-the-docs, semantic

Speaking experience

I have spoken at conferences on 3 continents, mostly in the realm of Documentation, Testing, and Django. From OSCON, Djangocon Prague, to Pycon Philippines.

More information here: http://ericholscher.com/speaking/

Speaker