Lincoln Loop

Django Best Practices

This post got a bit long-winded, skip to the project announcment if you prefer.

One of the things I love about Python and Django is the philosophy that there is one obvious way to do things. Standards make it easy to dive into other people’s code and figure out what is going on pretty quickly. As with anything under active development, however, those standards are subject to change over time. What was best practice for building sites with Django 0.91 is significantly different than building sites with Django 1.0. Better tools and more experience allow us to refine our processes over time into a set of best practices. While both Python and Django are very well documented, much of the experience and wisdom that is outside the scope of the official documentation is not.

Blogs are Bad for Documentation

Most of this information lives scattered across blogs, mailing lists, books, and the IRC channel. None of these avenues make it easy for developers to learn how to do things the “one obvious way.” There is a lot of stale information floating around out there, some of which we are guilty of creating. We try to blog about how we write and deploy code at Lincoln Loop, but like everyone else out there, we’re utilizing new tools and techniques on a regular basis. Our posts become outdated, but still get lots of hits from users searching for answers. Blogs and mailing lists are great for getting the word out there, but they aren’t true documentation of our growing ecosystem. What’s really needed is a living document.

Sphinx is Good for Documentation

Thankfully, Eric Holscher and Brian Rosner’s Reusable App Docs project got the ball rolling on creating this documentation. It’s focused on giving Django developers a comprehensive manual for building reusable Django applications. Better yet, it is open source and can be generated into any number of formats using the amazing Sphinx documentation generator.

Scratching the Itch

Our team has grown recently and it was important to us that everyone here develop using the same technique and style. Our intranet pointed to Eric and Brian’s project, but quickly started expanding on it. Without realizing it, we created documentation on Django best practices and realized we shouldn’t keep it hidden. I spoke to Eric about forking the project and expanding upon it since our scope was outside of the original documentation he and Brian created. With his blessing we started django-best-practices at GitHub. We’ve started some brain dumps into the document already and hope to chip away at it over time.

p(#the-goods). You can find a live copy of Django Best Practices at http://lincolnloop.com/django-best-practices/. We’ll still blog about new tips and tricks, but link those posts to the live document so people can always get up-to-date information. If you’re interested in following our progress, you can also follow the project feed.

Comments

• April 9, 2009 at 3:47 p.m. #
  Nick responded:

  Great idea!

  Adding comments to Best Practices would be great. Or any other feedback mechanism (like one in django book or similar).

  Thank you

• April 10, 2009 at 6:43 a.m. #
  Jiri Barton piped up:

  +1
  for Nick.

  How do you configure the Apache backend? I’d be very interested to know the bits with virtualenv.

  I can’t see any PROJECT/apps directory – the one the Reusable App Docs project uses. Does it mean you actually install all your project applications? By project applications I mean all the applications specific to your project, and by installing I mean installing into the virtualenv.

  Thank you

• April 11, 2009 at 12:50 a.m. #
  rates chimed in with:

  Yes, Django has really great design philosophy that saves a lot of time.

• April 13, 2009 at 12:48 p.m. #
  Peter Baumgartner commented:

  Thanks for the feedback all. Comments are now enabled via Disqus.

• March 16, 2010 at 12:49 a.m. #
  Derek responded:

  I’ve been able to build the document in HTML, using Sphinx, but get an error when trying to build the PDF version :
  Could not import extension rst2pdf.pdfbuilder (exception: cannot import name PDFPageLabel)
  I have installed rst2pdf itself.

• March 16, 2010 at 12:10 p.m. #
  Peter Baumgartner mentioned:

  @Derek
  You should use Sphinx to build to PDF as well (via LaTeX as an intermediary). You may find this info helpful: http://jimmyg.org/blog/2009/sphinx-pdf-generation-with-latex.html

Got something to say?

Name
Email
Website
Comment