Sphinx Training by Read the Docs

Welcome to the Read the Docs Sphinx Training website. We are the documentation experts.

We use this experience to help you understand how to leverage documentation in your business.

Having great documentation lowers your support costs, gets users onboarded faster, and is a requirement for shipping quality software. We are experts in the tools and process that produce great documentation. Help us improve how your company does documentation today.

We offer standard training courses, as well as custom training based on your needs. If one of the classes below looks good, we can deliver it on site at your company.

Testimonials

I just wanted to send a short note to say thanks for the the great tutorial on Sphinx. I knew nothing about either going in, but really needed to learn as I needed to get some documentation completed for my small clustering library which has become increasingly popular. I’m happy to say that I now have documentation up at http://hdbscan.readthedocs.io/en/latest/ and it is all thanks to your tutorial! It provided me with everything I needed to go from nothing to actually having good looking hosted documentation.

Courses

We provide a couple different courses to fit any range of experience.

Introduction to Sphinx

This 1-day course covers how to write documentation using RST and Sphinx 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.

The main things covered in this talk will be:

  • Why documentation is important
  • How to write good documentation
  • What parts of documentation are important
  • Semantic Markup
  • RST basics
  • Sphinx basics
  • How to include Sphinx into your development workflow
  • Building extensions to Sphinx

Details

The first 30 minutes will start with 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.

The last major section of content will be extending Sphinx. This allows users to take an already powerful tool and extend it to meet their needs. We’ll implement a custom role that links to the project’s bugtracker, and then a custom directive that lets us specify a specific filename in code examples. Understanding how to extend Sphinx really unlocks the power in the tool.

At the end, we’ll walk through some examples of some more advanced and interesting features and concepts in Sphinx, guided by questions that users have in the class.

Contact

You can contact us at training@readthedocs.com for more information on our training classes. We look forward to working with you!