Packaging, Documenting, and Distributing your Python Codebase
log in to bookmark this presentaton
Abstract
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.