Read the Docs

by Eric Holscher

Note

arrived late. :(

Intro

  • launched in Django Dash 2010
  • Makes documentation hosting trivial
  • uses sphinx

Things you can do

  • Post commit hooks on Github
  • Add custom sphinx theme
  • PDF generation via download think
  • Use their REST API for links to http://djangopackages.com

CNAME support

  • Request for docs.fabfile.org
  • docs.fabfile.org > (need to finish this out)

Architecture

  • Python

  • Front end caching via varnish

    • Varnish is the current single point of failure.
  • Django front ended via gunicorn and nginx

    • Docs are hosted out via nginx
  • Postgres SQL

  • Haystack and SOLR

  • Chef for deployment

  • Nagios & Munin

  • CoffeeScript (Where is the Python version? This is only in Ruby)

  • CLI support via http://rtd.rtfd.org (need to check this out!)

Open source!

Pros:

  • Patches
  • People trust you most because they can see the code
  • BSD license

Cons:

  • Known architecture information was on github
  • Early version had exposed data like IP addresses and other things

Hoping it makes people write more docs

  • mod_wsgi
  • django-piston

Lessons Learned

  • Think about your URLs. Really hard

    • Adding versions was hard
  • Lay your project out sanely

    • started with no tests
    • Shoved code in
    • Racked up a lot of technical debt
    • worked hard to make the project layout a bit more sane
  • Write tests!

    • Had a complicated code base without tests
    • They have hosted continuous integration
  • Build around a standard tool

    • Lots of good communication between rtfd and Sphinx
  • Passing data through systems is hard

  • Serving static files is annoying

  • Log. Everything.

    • Hard to find people’s problems until they added sophisticated logging
    • I personally like the build reports
  • Promote your projects!

  • Find a designer

  • Follow the Unix Philosophy

    • Do one thing and do it well
    • Stay to your project goal and don’t deviate
    • RTFD does so well cause all it does is Sphinx documentation hosting
  • Have a mission

    • RTFD fixes the problem in open source that projects are not well documented
    • WIKIs are where your project goes to die
    • Sphinx lets you accept Pull Requests

Sponsors

  • Revsys
  • PSF
  • Divio
  • pyladies

Questions

Note

ask Russ his question

  • How easy to deploy internally?

    • Open Source
    • Documented
    • Chef
  • Designer thoughts?

    • Started with the project with a designer

Mirror your project in your test layouts

Note

I love this pattern and use it myself!

  • Create test modules following the same file layout as your project

  • Have as few root test utils as possible

    • Use it sparingly
    • just a few simple helper functions!