readthedocs.org

I just discovered readthedocs.org today, and it's awesome! The organization behind the site will build and host documentation for any open source project. It works with any projects that use sphinx/reStructuredText for their documentation.

I'm a fan of reST (reStructuredText). Its semantic processing of whitespace can be confusing when you're first starting out, and the format used for tables can be cumbersome if your tables are complex, but you get used to it.

I write these blog posts in reST, I write notes in reST, and recently I started using reST + sphinx to document an open source project.

I considered using github's wiki feature for project documentation, but after reading about it, I decided not to use it. As of this writing, it does not support auto-building documentation in HTML format from markup formats defined in your main project source tree. You can use git for your project wiki/docs, but github will create a separate git repo for the documentation.

With sphinx, you can take your reST sources and build documentation in multiple formats. readthedocs.org supports html, epub, and pdf out of the box!

readthedocs.org uses a build system that scans your project source tree to find the conf.py at the root of your sphinx documentation. My project had the sphinx docs rooted in src/site/sphinx, with the conf.py in the source subdirectory, and ReadTheDocs was able to find this and build my documentation without requiring me to specify the paths. All I had to do was:

• sign up for an account on readthedocs.org
• configure a new project on ReadTheDocs and specify the read-only-access url of my github project in the ReadTheDocs project configuration form.

And that was it! ReadTheDocs checked out my project source, built the documentation in html format, and published it here.

If you customize your sphinx layout, you have to contact the ReadTheDocs team to whitelist your custom configuration (this may be automated in the future). Otherwise, ReadTheDocs will build your documentation with a some default sphinx settings.

ReadTheDocs also provides a unique web service endpoint that you can call to rebuild your documentation. Github provides a custom post-commit hook for ReadTheDocs that can be configured on your github project page by navigating to:

admin -> service hooks -> ReadTheDocs

Once you do that, your documentation will be rebuilt automatically every time you push code to master. Otherwise, by default, the documentation will be rebuilt nightly.