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 setup.py 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 packages.python.org

Requirements

Laptop with Python 2.5 or 2.6 installed.