Introduction to Sphinx & Read the Docs*
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.
This talk will have four parts:
- Why Write Documentation
- Semantic Markup
- 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.
documentation, sphinx, docs, read-the-docs, semantic
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/
Read the Docs
Eric is a maintainer of Read the Docs, an open source documentation hosting service, and co-creator of Write the Docs. He also lived in the woods for over 2 months while walking 800 miles of the Pacific Crest Trail in 2013.
- Title: Introduction to Sphinx & Read the Docs
- Track: Chemistry
- Room: B201
- Time: 1:30 – 2:15pm
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.
- Speakers: Eric Holscher