Real Ultimate Programming

The Home for People Who Like to Flip Out and Write Code

Notes From PyATL 2013-01-10

  • Georgia Tech Research Institute (GTRI) is hiring web developers

tox: State of the Art in Testing (Alfredo Deza)

  • Written by Holger Krekel, involved with py.test, helped start PyPy (no longer active), and generally helpful guy.
  • virtualenv-based automation of test activities
  • So is this turning into a Continuous Integration (CI)solution?
  • Supports different Python interpreters (this is how I first learned about it)
  • testrunner-agnostic
  • Even if you don’t need to support multiple Pythons, this still has benefits:
    • Makes sure your package can be built/installed outside your dev environment
    • Abstracts away from special start scripts, callables, etc. for your CI server
    • Oops. Alfredo used one of Rick’s libs as an example, but Rick couldn’t make it tonight.
  • Not only can you run tests, you can execute any command you want against it, so you can, for example, use it to build your Sphinx docs.
  • Apparently, there’s a very big release just around the corner.

Better Documentation Through Automation: Creating docutils & Sphinx Extensions (Doug Hellmann)

  • Biggest difference between ReStructuredText (rst)? It was designed from the ground up to be extensible.
  • Pieces:
    • Sphinx Application
    • Build Environment
    • docutils parser
    • Sphinx Builder
  • Common extension points: parser and builder.
  • Extensions manipulate the parse tree

Extending docutils

### Roles vs. Directives #### Roles

  • Inline, e.g., :bbissue:68
  • If we had a more serious doc project, I’d be writing custom roles left and right; they’re simple, yet powerful.
  • The implementation is a simple function that returns a list of nodes
  • Nice: it gives you error helpers; nice to see they thought about the failure cases
  • You use the setup function to wire your extension into the Sphinx machinery


  • More powerful than roles, at the expense of lots more pieces to keep track of
  • These are things like the .. note:: directive in vanilla Sphinx
  • I like Doug’s sample directive; nothing like using a database to build your docs to make sure your docs are legit.
  • Since it’s so much more sophisticated, the implementation is a class.
  • You’ll probably need to implement the run method, if nothing else. Like a role processor, this function returns a list of nodes.

Sphinx-specific extensions

Extending the Sphinx Builder

  • This is how Doug made his spellchecker for Sphinx docs.
  • The concepts here aren’t hard, but you’re gonna get really familiar with Sphinx internals if you start doing this.
  • A good thing to remember: set the exit code to something that is not 0 when you encounter an error. Remember, only YOU can fight crappy CLI experiences.

Back to flipping out…