Setting up agile development with Python/Komodo (part 4)
This is the fourth and final part in a series of tutorials on setting up a Python project in Komodo Edit for agile development.
In part 1, we set up automated testing, and started our automated build script. In part 2, we added building an executable and setup program to our build script. In part 3, we added installation and function testing to our build script. In this part, we're going to automatically generate API documentation for our project using epydoc, then put our project under source control using Mercurial, and add a commit to our build script.
So let's get started. First, make sure you've downloaded and installed epydoc and Mercurial.
Generate documentation
First, add a blank file "__init__.py" to your project. This will make "TestProject" a package, so epydoc can do its magic.
Now, add the file "genapidocs.py" to your project, as follows:
"""
Generate API documentation for the project
"""
import os
from setup import clean_dir
from build import run_command
NAME = "AgileDevelopment" # DRY violation!
DOT_PATH = os.path.abspath("/program files/att/graphviz/bin/dot.exe")
def gen_api_docs():
"""Generates documentation files"""
print
print "*" * 30
print "Generating documentation…"
base_dir = os.path.dirname(__file__)
api_dir = os.path.join(base_dir, "apidocs")
# Get rid of the old documentation
clean_dir(api_dir)
os.chdir(base_dir)
run_command(' '.join([r'epydoc.py',
'–html',
'-v',
r'-o "%s"' % api_dir,
'–name=%s' % NAME,
'–graph all',
r'–dotpath "%s"' % DOT_PATH,
'–top=TestProject.main',
r'"%s"' % base_dir]))
print "Finished generating documentation!"
print "*" * 30
print
if __name__ == "__main__":
gen_api_docs()
In order to add pretty graphs to the documentation, I'm using the "graph all" command option, which requires Graphviz. I highly recommend downloading this program, but you can omit the graph all command (and dotpath command) if you want.
Now, update your build.py script's build command to include documentation:
"""Performs the automated build"""
curr_dir = os.path.dirname(__file__)
os.chdir(curr_dir)
# Unit tests
run_command('nosetests -w "%s"' % curr_dir)
# Build executable
run_command('setup.py')
# Build installer
base = "/program files/inno setup 5/iscc.exe"
inno = os.path.abspath(base)
run_command(r'"%s" setup.iss' % inno)
# Install application
run_command('install.py')
# Run function tests
base_dir = os.path.split(curr_dir)[0]
test_dir = os.path.join(base_dir, 'TestProjectFuncTests')
run_command('nosetests -w "%s"' % test_dir)
# Generate documentation
run_command('genapidocs.py')
Put the project under source control
Let's add a command to Komodo to show a command prompt for the current file's directory. Add a command to the toolbox, as follows:
Execute the command, and from the command line, enter the command
This will create our repository. We don't want to put automatically generated files under source control, so we can exclude them from source control with the .hgignore file (I use "vim .hgignore" from the command line to create it; use whatever works for you).
AgileApp/*
apidocs/*
build/*
Setup/*
Commit changes in build script
Now, each time we run our build script, we're going to commit our changes to our Mercurial repository. This way, we know that we are always checking in code that is correct according to our current understanding.
Modify the build function as follows (last time!):
"""Performs the automated build"""
curr_dir = os.path.dirname(__file__)
os.chdir(curr_dir)
# Unit tests
run_command('nosetests -w "%s"' % curr_dir)
# Build executable
run_command('setup.py')
# Build installer
base = "/program files/inno setup 5/iscc.exe"
inno = os.path.abspath(base)
run_command(r'"%s" setup.iss' % inno)
# Install application
run_command('install.py')
# Run function tests
base_dir = os.path.split(curr_dir)[0]
test_dir = os.path.join(base_dir, 'TestProjectFuncTests')
run_command('nosetests -w "%s"' % test_dir)
# Generate documentation
run_command('genapidocs.py')
# Commit changes
run_command('hg addremove')
run_command('hg commit')
Conclusion
The linked zip file (AgileProject.zip) contains our agile project, the project with the function tests, and the toolbox commands created in this tutorial.
We're now ready to start actual development of our project. This setup might have seemed like a lot of work, but it's very valuable, because as long as we keep up our unit tests and function tests, we can guarantee that our application is in a working state at all times.
The first thing I would normally do is get rid of the DRY violations by putting each piece of project metadata in a single location, then generating the other documents from that (e.g. using Mako to generate the setup.iss script automatically).
