• 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

Directives

• 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…