E-Scribe : a programmer’s blog

About Me

PBX I'm Paul Bissex. I build web applications using open source software, especially Django. Started my career In the 1990s doing graphic design for newspapers and magazines. Then I wrote technology commentary and reviews for Wired, Salon.com, Chicago Tribune, and lots of little places you've never heard of. Then I taught photographers how to create good websites. Then I helped a giant media corporation serve 40 million pages a day. Now I work on a small Django team at the largest translation company in the world. Feel free to email me.

Book

I co-wrote "Python Web Development with Django". It was the first book to cover the long-awaited Django 1.0. Published by Addison-Wesley and still in print!

Colophon

Built using Django, served with gunicorn and nginx. The database is SQLite. Hosted on a FreeBSD VPS at Johncompanies.com. Comment-spam protection by Akismet.

Pile o'Tags

ajax apple blogs browsers business design django ebay fp fun google hardware haskell intellectual property interface iphone javascript linux media mercurial mobile open source os x oscon oscon2007 palm php programming python rails rants reading risks ruby site spam textmate the well tips tools ubuntu unix vcs web development web frameworks webservers wmassdevs writing

Stuff I Use

bitbucket, Django, Emacs, FreeBSD, Git, jQuery, LaunchBar, Markdown, Mercurial, OS X, Python, Review Board, S3, SQLite, Sublime Text, Ubuntu Linux

Spam Report

At least 235572 pieces of comment spam killed since 2008, mostly via Akismet.

Booktools

A little-known bit of trivia about our book, Python Web Development with Django: we wrote the manuscript in Markdown.

I think it was my idea. One of the major motivations for using a text-based format -- versus the unfortunate de facto standard, Microsoft Word -- was integration with good developer tools and workflow.

Our manuscript and all our project code was in a Subversion repo, so each author always had the latest updates. HTML generated from the Markdown files was great for generating nice printed/printable output too.

We could have used any number of similar formats: Markdown, Textile, reStructuredText. If we did it again we'd probably use reST plus Sphinx. That would grant all the same advantages, plus give us a little more formatting flexibility and tool support.

This workflow enabled certain kinds of programmatic action on our text, notably two things: automated testing of the interactive examples within the text, and automated extraction of example snippets from source code files.

I wrote scripts for each of these tasks. I've cleaned them up a little, to try to make them a little more general-purpose, and published them (with minimal example files) in a bitbucket repo: http://bitbucket.org/pbx/booktools

There's a little documentation in the docstrings of the scripts. Here's the summary:

To test code snippets in the manuscript file: test_snippets.py example/text.txt

To extract code from source files into the manuscript file: try_excerpt.py example/text.txt

Authors, make use of this if you can -- or maybe even better, take inspiration from the idea and implement a system of your own.

Tuesday, September 14th, 2010
+ +
2 comments

Some related posts: Pocket Django • Book news: Rough Cuts and Amazon • A little something I've been working on • Bicycle Repair Man bundle for TextMate
• Comment from matt harrison , later that day

Very cool. I've been doing the same thing with reST (generating pdf, docs and presos) and having all the code tested. How many people have coverage reports for their docs?

• Comment from Paul , 3 days later

It's a good thing, eh? The first time I ran the example tester I found a slew of easy-to-fix errors.

Comments are closed for this post. But I welcome questions/comments via email or Twitter.