pycon logo

PyCon 2011 Atlanta

March 9th–17th

Log in or Sign Up

Packaging, Documenting, and Distributing your Python Codebase

log in to bookmark this presentaton

Novice / Tutorial
March 9th 1:20 p.m. – 4:40 p.m.
Distributing and Documenting code is a place where a lot of projects are held up because these things are often perceived as difficult to someone that just has a few python scripts lying around that they want to share. The aim of this tutorial is to train folks on how to package their software and provide an easier way to provide documentation.


The first part of this tutorial will focus on packaging, and how to create a repeatable install process. This is important because most python packages rely on other packages, and getting the dependencies to work is often a challenge with our current python packaging toolset. I will show attendees how to set up a private index whereby the user will have complete control over the packages that are installed. I will explain a little about how works in a package, and what we can do to ensure packages install as expected.

The second part of the tutorial will help the user get started with documentation. This is a skill I have shown a number of pythonistas in the past, and the result was documentation for Jython, ConfigObj, and others. I will show users how Sphinx can provide both a narrative and api-style documentation for their codebase, and how that documentation becomes a living, tested document through the usage of doctests.

For this tutorial, people are welcome to bring their own code that they'd like to document and/or distribute. I am happy to work on the fly with an existing codebase, and will have a few volunteers lined up to help me with this.

Intro Talk

A 15 minute talk about packaging, distribution, and the problems usingtools like Paster, PIP, Virtualenv, and Basketweaver solve. Also, I will introduce Sphinx, and describe the way the class will work.

Part I

  • Installation of virtualenv, pastescript, pip, and basketweaver (5 minutes)
  • Creation of a "development" virtualenv. (5 minutes)
  • Participant volunteers to explain their codebase. (5 minutes)
  • Splitting into groups, and sharing codebases. (15 minutes)
  • Using PasteScript to create a package, install that package, and create a distributable egg. (15 minutes)
  • Modifying your egg to depend on other python packages. (5 minutes)* Creating a personal pypi using basketweaver. (10 minutes)
  • Creation of a "deployment" virtualenv. (5 minutes)
  • Loading your deployment virtualenv with your new package. (10 minutes)
  • (optional) uploading your package to the official pypi
  • (optional) discussion on namespacing

Part II

  • Installation of Sphinx (5 minutes)
  • Quickstart of sphinx package, HTML generation ( 10 minutes)
  • Review of ReST formatting ( 10 minutes)
  • Generating docs from your package's docstrings (10 minutes)
  • Autodoc Discussion. (10 minutes)
  • Adding and testing example source code. (30 minutes)
  • Theming and adding Feedback mechanisms. (15 minutes)
  • (optional) Adding your package documentation to


Laptop with Python 2.5 or 2.6 installed.