DjangoCon 2011 – The story and tech of Read the Docs

With the morning tracks over and a delicious lunch finished we’ll be diving into the afternoon talks with ‘The story and tech of Read the Docs’ by Eric Holscher.

Hosting open source documentation was a mess. The best-of-class solution for the Python world as uploading a tarball of html to packages.python.org or doing similar to upload to github pages.. We set out to solve this problem using the current best of class tools that Django has to offer.

Updates below:

17.09

That’s all folks. Great talk by Eric

17.08

“Get the designer involved from the planning.” Designers are often better at UX than developers.

17.07

Because RTD is open source you can easily install it in your local environment to host private repositories. Especially useful for large companies that don’t want their documents public.

17.04

Revsys, Python Software Foundation, Mozilla, Divio and PyLadies have all helped the site through donations, servers, and such.

17.01

Have a mission and stick to it.

17.01

Follow the Unix Philosophy. Do one thing and do one thing well.

17.00

Find a designer. An appealing design has helped Read The Docs

16.59

Promote your projects. Write blog posts, give talks at conferences, explain what it does.

16.53

Lessons Learned from RTD

  • Think really hard about your URLs
  • Lay your project out sanely
  • Write tests
  • Build around a standard tool
  • Passing data through systems is hard
  • Serving static files is annoying
  • Log Everything.

16.49

“People trust you more when they can see the code”

16.49

Must be careful with Open Source projects. Because everything is in the public it can be easier for people to take advantage of it.

16.48

Runs Nginx in-front of Gunicorn. Nginx has buffering.

16.44

Using Upstart (Ubuntu init.d replacement) for all of their processes.

16.43

Uses Chef for building their web servers.

16.42

Haystack & Solr for search.

16.42

Technical Architecture
  • Varnish for static hosting
  • Nginx & Gunicorn for their Django Processes
  • PostgreSQL for DB
  • Even if they lose their Postgres, they can serve all of the content.
Varnish is the only single point of failure. Everything else is duplicated.

16.39

RTFD.org is their short URL.

16.38

PDF generation of all documentation.

16.37

Built their own custom Sphinx theme. Has full-text search through a solr backend.

16.37

Uses post commit hooks (also in GitHub). Supports all major version controls

16.36

Read The Docs was built in 24 hours by 3 people.

16.32

Read The Docs came from 2010 Django Dash

16.30

@ericholscher taking the stage.

Also read...