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.
That’s all folks. Great talk by Eric
“Get the designer involved from the planning.” Designers are often better at UX than developers.
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.
Have a mission and stick to it.
Follow the Unix Philosophy. Do one thing and do one thing well.
Find a designer. An appealing design has helped Read The Docs
Promote your projects. Write blog posts, give talks at conferences, explain what it does.
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.
“People trust you more when they can see the code”
Must be careful with Open Source projects. Because everything is in the public it can be easier for people to take advantage of it.
Runs Nginx in-front of Gunicorn. Nginx has buffering.
Using Upstart (Ubuntu init.d replacement) for all of their processes.
Uses Chef for building their web servers.
Haystack & Solr for search.
- 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.
RTFD.org is their short URL.
PDF generation of all documentation.
Built their own custom Sphinx theme. Has full-text search through a solr backend.
Uses post commit hooks (also in GitHub). Supports all major version controls
Read The Docs was built in 24 hours by 3 people.
Read The Docs came from 2010 Django Dash
@ericholscher taking the stage.