Merge lp:~leonardr/launchpad/multiversion-apidoc into lp:launchpad/db-devel

[Leonard Richardson]

This branch makes Launchpad generate an HTML apidoc for every version of the web service, not just the devel version. The apidoc for version "foo" is written to lib/canonical/launchpad/apidoc/foo.html, and index.html is now a short list of links to the version-specific documentation files.

This branch renames create-lp-wadl.py to create-lp-wadl-and-apidoc.py, giving it repsonsibility for converting the WADL into the API doc and generating the index.html. The apiindex.py file is removed. (I couldn't this file used anywhere but the Makefile.)

I would really like feedback on the following issues:

1. Is there a way to put apidoc-index.pt somewhere else? Maybe in lib/canonical/launchpad/templates? I couldn't get this to work with pkg_resources because l.c.l.t isn't a module.
2. Is there a way to look up config/active_versions/$version in the template file? If so, I can get rid of versions_and_descriptions.

This branch still needs a little bit of work--I need to fix up the apidoc test so it tests the new system.

[Leonard Richardson (leonardr)]

The diff is screwed up due to the precursor branch being out-of-date, but here's a paste: http://pastebin.ubuntu.com/393568/

[Leonard Richardson (leonardr)]

One test on EC2 failed: the title of the generated apidoc is now "About this service", not "Launchpad Web Service API". Our XSLT stylesheet (which is based on Mark Nottingham's general WADL stylesheet) has this code:

        <xsl:variable name="title">
            <xsl:choose>
                <xsl:when test="wadl:doc[@title]">
                    <xsl:value-of select="wadl:doc[@title][1]/@title"/>
                </xsl:when>
                <xsl:otherwise>Launchpad Web Service API</xsl:otherwise>
            </xsl:choose>
        </xsl:variable>

Previously the WADL's <application> tag had no <doc> children, so we used the default. Now there are two <doc> tags, "About this service" and "About version {version}".

This is actually pretty nice; I was afraid I would have to hack the XSLT to add the <doc> tags to the HTML, but it already processes them. The only problem is that the XSLT stylesheet uses the title of the first <doc> tag as the title of the whole document, and ignores the title of all subsequent <doc> tags. I was hoping for this (#1):

---
<h1>Launchpad Web Service API</h1>

<h2>About this service</h2>

The Launchpad web service allows automated clients to access most of the functionality available on the Launchpad web site. For help getting started, see the help wiki.

<h2>About version beta</h2>

This is the first version of the web service ever published. Its end-of-life date is April 2011, the same as the Ubuntu release "Karmic Koala".
---

And upon reflection I think this would be even better (#2):

---
<h1>Launchpad web service, version beta</h1>

The Launchpad web service allows automated clients to access most of the functionality available on the Launchpad web site. For help getting started, see the help wiki.

This is the first version of the web service ever published. Its end-of-life date is April 2011, the same as the Ubuntu release "Karmic Koala".
---

Instead, we have this (#3):

---
<h1>About this service</h1>

The Launchpad web service allows automated clients to access most of the functionality available on the Launchpad web site. For help getting started, see the help wiki.

This is the first version of the web service ever published. Its end-of-life date is April 2011, the same as the Ubuntu release "Karmic Koala".
---

We can change the stylesheet to get #1 and change lazr.restful to get #2. But I think what we have now is good enough that I can file a bug and come back to fix the generated documentation later. What do you think?

[Leonard Richardson (leonardr)]

And here's another diff against the precursor branch: http://paste.ubuntu.com/395661

[Aaron Bentley (abentley)]

Please use extract_text if possible. Otherwise, this looks fine.

review: Approve

[Gary Poster (gary)]

Leonard asked me to take a look at this because of his two specific questions.

1. Is there a way to put apidoc-index.pt somewhere else? Maybe in lib/canonical/launchpad/templates? I couldn't get this to work with pkg_resources because l.c.l.t isn't a module.

The FilePageTemplate just expects a path. I'm relatively confident that you can use os.path fun, combined with module __file__ fun, to do what you describe. However, as we agreed on IRC, I'm fine with what you are doing now.

2. Is there a way to look up config/active_versions/$version in the template file? If so, I can get rid of versions_and_descriptions.

The infrequently used syntax for this is "?," I believe. In other words, if you have a variable named "config" and a variable named "version" that contains the string "beta", "config/active_versions/?version" is supposed to be equivalent to "config/active_versions/beta".

On a separate note, also as we discussed on IRC, this segment from create-lp-wadl-and-apidoc.py looks to me like it ought to be simplified.

1115 + # Finally, create an index.html with links to all the HTML
1116 + # documentation files we just generated.
1117 + template_file = 'apidoc-index.pt'
1118 + template = PageTemplateFile(template_file)
1119 + namespace = template.pt_getContext()
1120 + namespace['config'] = config
1121 + versions_and_descriptions = []
1122 + for version in config.active_versions:
1123 + versions_and_descriptions.append(
1124 + dict(version=version,
1125 + description=config.version_descriptions[version]))
1126 + namespace['versions_and_descriptions'] = versions_and_descriptions
1127 +
1128 + f = open(os.path.join(directory, "index.html"), 'w')
1129 + f.write(template.pt_render(namespace))

This could be simplified to the following:

    template_file = 'apidoc-index.pt'
    template = PageTemplateFile(template_file)
    versions_and_descriptions = []
    for version in config.active_versions:
        versions_and_descriptions.append(
            dict(version=version,
                 description=config.version_descriptions[version]))

    f = open(os.path.join(directory, "index.html"), 'w')
    f.write(template(config=config,
                     versions_and_descriptions=versions_and_descriptions))

Then in your template you would access config and versions_and_descriptions off of the "options" object in the page template.

If you use the ? syntax I mentioned above for options/config/version_descriptions/?version, of course, then this could be further simplified to just this:

    template_file = 'apidoc-index.pt'
    template = PageTemplateFile(template_file)
    f = open(os.path.join(directory, "index.html"), 'w')
    f.write(template(config=config))

That's way nicer, I think.

=== modified file '.bzrignore'
--- .bzrignore	2010-03-09 02:42:40 +0000
+++ .bzrignore	2010-03-15 21:11:07 +0000
@@ -30,9 +30,9 @@
 database/sampledata/newsampledata-dev.sql
 database/sampledata/lintdata.sql
 database/sampledata/lintdata-dev.sql
-lib/canonical/launchpad/apidoc/index.html
+lib/canonical/launchpad/apidoc/*.html
 xxx-report.*
-lib/canonical/launchpad/apidoc/wadl-development.xml
+lib/canonical/launchpad/apidoc/wadl-development-*.xml
 lib/canonical/launchpad/apidoc/wadl-test-playground.xml
 lib/canonical/launchpad/icing/build/*
 lib/canonical/launchpad/icing/combo.css

=== modified file 'Makefile'
--- Makefile	2010-03-05 21:47:03 +0000
+++ Makefile	2010-03-15 21:11:07 +0000
@@ -30,7 +30,6 @@
 
 APIDOC_DIR = lib/canonical/launchpad/apidoc
 WADL_TEMPLATE = $(APIDOC_DIR).tmp/wadl-$(LPCONFIG)-%(version)s.xml
-DEVEL_WADL_FILE = $(APIDOC_DIR)/wadl-$(LPCONFIG)-devel.xml
 API_INDEX = $(APIDOC_DIR)/index.html
 
 # Do not add bin/buildout to this list.
@@ -60,16 +59,12 @@
 hosted_branches: $(PY)
 	$(PY) ./utilities/make-dummy-hosted-branches
 
-$(DEVEL_WADL_FILE): $(BZR_VERSION_INFO)
+$(API_INDEX): $(BZR_VERSION_INFO)
 	mkdir $(APIDOC_DIR).tmp
-	LPCONFIG=$(LPCONFIG) $(PY) ./utilities/create-lp-wadl.py "$(WADL_TEMPLATE)"
+	LPCONFIG=$(LPCONFIG) $(PY) ./utilities/create-lp-wadl-and-apidoc.py "$(WADL_TEMPLATE)"
 	mv $(APIDOC_DIR).tmp/* $(APIDOC_DIR)
 	rmdir $(APIDOC_DIR).tmp
 
-$(API_INDEX): $(DEVEL_WADL_FILE)
-	bin/apiindex $(DEVEL_WADL_FILE) > $@.tmp
-	mv $@.tmp $@
-
 apidoc: compile $(API_INDEX)
 
 check_merge: $(PY)
@@ -259,7 +254,7 @@
 $(BZR_VERSION_INFO):
 	scripts/update-bzr-version-info.sh
 
-support_files: $(DEVEL_WADL_FILE) $(BZR_VERSION_INFO)
+support_files: $(API_INDEX) $(BZR_VERSION_INFO)
 
 # Intended for use on developer machines
 start: inplace stop support_files initscript-start
@@ -330,9 +325,10 @@
 	$(RM) -r $(CODEHOSTING_ROOT)
 	mv $(APIDOC_DIR)/wadl-testrunner-devel.xml \
 	    $(APIDOC_DIR)/wadl-testrunner-devel.xml.bak
-	$(RM) $(APIDOC_DIR)/wadl*.xml $(API_INDEX)
+	$(RM) $(APIDOC_DIR)/wadl*.xml $(APIDOC_DIR)/*.html
 	mv $(APIDOC_DIR)/wadl-testrunner-devel.xml.bak \
 	    $(APIDOC_DIR)/wadl-testrunner-devel.xml
+	$(RM) -rf $(APIDOC_DIR).tmp
 	$(RM) $(BZR_VERSION_INFO)
 	$(RM) _pythonpath.py
 	$(RM) -rf \

=== modified file 'lib/canonical/buildd/debian/launchpad-buildd.init'
--- lib/canonical/buildd/debian/launchpad-buildd.init	2009-12-16 00:16:24 +0000
+++ lib/canonical/buildd/debian/launchpad-buildd.init	2010-03-15 21:11:07 +0000
@@ -29,7 +29,7 @@
     CONF=$1
     PIDFILE="$PIDROOT"/"$CONF".pid
     LOGFILE="$LOGROOT"/"$CONF".log
-    su - buildd -c "BUILDD_SLAVE_CONFIG=$CONFROOT/$CONF PYTHONPATH=/usr/share/launchpad-buildd twistd --no_save --pidfile $PIDFILE --python $TACFILE --logfile $LOGFILE"
+    su - buildd -c "BUILDD_SLAVE_CONFIG=$CONFROOT/$CONF PYTHONPATH=/usr/share/launchpad-buildd twistd --no_save --pidfile $PIDFILE --python $TACFILE --logfile $LOGFILE --umask 022"
 }
 
 #

=== modified file 'lib/canonical/launchpad/pagetests/webservice/apidoc.txt'
--- lib/canonical/launchpad/pagetests/webservice/apidoc.txt	2008-07-31 21:23:02 +0000
+++ lib/canonical/launchpad/pagetests/webservice/apidoc.txt	2010-03-15 21:11:07 +0000
@@ -1,9 +1,23 @@
 = API Documentation =
 
-The up-to-date Launchpad API documentation is available from
-http://launchpad.dev/+apidoc.
+The Launchpad API documentation portal is available at
+http://launchpad.dev/+apidoc. It contains summaries of the different
+web service versions, and links to version-specific documents.
 
     >>> browser.open('http://launchpad.dev/+apidoc')
+    >>> print extract_text(browser.contents)
+    Launchpad Web Service API
+    Launchpad web service API documentation
+    ...
+    Active versions
+    ...
+    devel: This version of the web service reflects the most recent...
+    ...
+
+The documentation for a specific version is located at
+http://launchpad.dev/+apidoc/{version}.html.
+
+    >>> browser.open('http://launchpad.dev/+apidoc/devel.html')
     >>> print browser.title
-    Launchpad Web Service API
+    About this service
 

=== added file 'lib/canonical/launchpad/pagetests/webservice/multiversion.txt'
--- lib/canonical/launchpad/pagetests/webservice/multiversion.txt	1970-01-01 00:00:00 +0000
+++ lib/canonical/launchpad/pagetests/webservice/multiversion.txt	2010-03-15 21:11:07 +0000
@@ -0,0 +1,32 @@
+Differences between versions
+----------------------------
+
+In the 'beta' version of the web service, mutator methods like
+IBugTask.transitionToStatus are published as named operations. In
+subsequent versions, those named operations are not published.
+
+  >>> def get_bugtask_path(version):
+  ...     bug_one = webservice.get("/bugs/1", api_version=version).jsonBody()
+  ...     bug_one_bugtasks_url = bug_one['bug_tasks_collection_link']
+  ...     bug_one_bugtasks = sorted(webservice.get(
+  ...         bug_one_bugtasks_url).jsonBody()['entries'])
+  ...     bugtask_path = bug_one_bugtasks[0]['self_link']
+  ...     return bugtask_path
+
+Here's the 'beta' version, where the named operation works.
+
+  >>> url = get_bugtask_path('beta')
+  >>> print webservice.named_post(
+  ...     url, 'transitionToImportance', importance='Low',
+  ...     api_version='beta')
+  HTTP/1.1 200 Ok
+  ...
+
+Now let's try the same thing in the '1.0' version, where it fails.
+
+  >>> url = get_bugtask_path('1.0')
+  >>> print webservice.named_post(
+  ...     url, 'transitionToImportance', importance='Low',
+  ...     api_version='devel')
+  HTTP/1.1 405 Method Not Allowed
+  ...

=== modified file 'lib/canonical/launchpad/rest/configuration.py'
--- lib/canonical/launchpad/rest/configuration.py	2010-02-15 02:09:32 +0000
+++ lib/canonical/launchpad/rest/configuration.py	2010-03-15 21:11:07 +0000
@@ -24,9 +24,30 @@
 
     path_override = "api"
     active_versions = ["beta", "1.0", "devel"]
+    last_version_with_mutator_named_operations = "beta"
     view_permission = "launchpad.View"
     set_hop_by_hop_headers = True
 
+    service_description = """The Launchpad web service allows automated
+        clients to access most of the functionality available on the
+        Launchpad web site. For help getting started, see
+        <a href="https://help.launchpad.net/API/">the help wiki.</a>"""
+
+    version_descriptions = {
+        "beta": """This is the first version of the web service ever
+        published. Its end-of-life date is April 2011, the same as the
+        Ubuntu release "Karmic Koala".""",
+
+        "1.0": """This version of the web service removes unnecessary
+        named operations. It was introduced in March 2010, and its
+        end-of-life date is April 2015, the same as the server version
+        of the Ubuntu release "Lucid Lynx".""",
+
+        "devel": """This version of the web service reflects the most
+        recent changes made. It may abruptly change without
+        warning. Periodically, these changes are bundled up and given a
+        permanent version number.""" }
+
     @property
     def use_https(self):
         return config.vhosts.use_https

=== modified file 'lib/canonical/launchpad/webapp/tests/test_servers.py'
--- lib/canonical/launchpad/webapp/tests/test_servers.py	2010-02-24 14:45:33 +0000
+++ lib/canonical/launchpad/webapp/tests/test_servers.py	2010-03-15 21:11:07 +0000
@@ -14,7 +14,7 @@
 from lazr.restful.interfaces import (
     IServiceRootResource, IWebServiceConfiguration)
 from lazr.restful.simple import RootResource
-from lazr.restful.tests.test_webservice import (
+from lazr.restful.testing.webservice import (
     IGenericCollection, IGenericEntry, WebServiceTestCase)
 
 from lp.testing import TestCase

=== modified file 'lib/lp/bugs/stories/webservice/xx-bug.txt'
--- lib/lp/bugs/stories/webservice/xx-bug.txt	2010-03-10 14:14:38 +0000
+++ lib/lp/bugs/stories/webservice/xx-bug.txt	2010-03-15 21:11:07 +0000
@@ -357,7 +357,7 @@
   http://.../~cprov
 
 
-The task's importance can be modified directly...
+The task's importance can be modified directly.
 
   >>> body = webservice.get(bugtask_path).jsonBody()
   >>> body['importance']
@@ -371,20 +371,6 @@
   >>> body['importance']
   u'High'
 
-...or through a named operation.
-
-  >>> print webservice.named_post(
-  ...     bugtask_path, 'transitionToImportance', importance='Low')
-  HTTP/1.1 200 Ok
-  ...
-  Content-Type: application/json
-  ...
-  <BLANKLINE>
-  null
-  >>> body = webservice.get(bugtask_path).jsonBody()
-  >>> body['importance']
-  u'Low'
-
 Only bug supervisors or people who can otherwise edit the bugtask's
 pillar are authorised to edit the importance.
 
@@ -394,10 +380,9 @@
 
   >>> body = webservice.get(bugtask_path).jsonBody()
   >>> body['importance']
-  u'Low'
+  u'High'
 
-The task's status is another aspect of the task that can be modified
-either directly or through a named operation.
+The task's status can also be modified directly.
 
   >>> print webservice.get(bugtask_path).jsonBody()['status']
   Confirmed
@@ -409,21 +394,14 @@
   >>> print webservice.get(bugtask_path).jsonBody()['status']
   Fix Committed
 
-  >>> print webservice.named_post(
-  ...     bugtask_path, 'transitionToStatus', status='New')
-  HTTP/1.1 200 Ok...
-
-  >>> print webservice.get(bugtask_path).jsonBody()['status']
-  New
-
 If an error occurs during a request that sets both 'status' and
 'importance', neither one will be set.
 
   >>> task = webservice.get(bugtask_path).jsonBody()
   >>> print task['status']
-  New
+  Fix Committed
   >>> print task['importance']
-  Low
+  High
 
   >>> patch = {u'importance': 'High', u'status': u'No Such Status'}
   >>> print webservice.patch(bugtask_path, 'application/json', dumps(patch))
@@ -431,12 +409,11 @@
 
   >>> task = webservice.get(bugtask_path).jsonBody()
   >>> print task['status']
-  New
+  Fix Committed
   >>> print task['importance']
-  Low
+  High
 
-Like the importance, the milestone can be set either directly or via a
-named operation, and only by appropriately privileged users.
+The milestone can only be set by appropriately privileged users.
 
   >>> print webservice.get(bugtask_path).jsonBody()['milestone_link']
   None
@@ -449,20 +426,12 @@
   >>> print webservice.get(bugtask_path).jsonBody()['milestone_link']
   http://.../debian/+milestone/3.1
 
-  >>> print webservice.named_post(
-  ...     bugtask_path, 'transitionToMilestone',
-  ...     milestone=webservice.getAbsoluteUrl('/debian/+milestone/3.1-rc1'))
-  HTTP/1.1 200 Ok...
-
-  >>> print webservice.get(bugtask_path).jsonBody()['milestone_link']
-  http://.../debian/+milestone/3.1-rc1
-
   >>> print user_webservice.patch(
   ...     bugtask_path, 'application/json', dumps(patch))
   HTTP/1.1 401 Unauthorized...
 
   >>> print webservice.get(bugtask_path).jsonBody()['milestone_link']
-  http://.../debian/+milestone/3.1-rc1
+  http://.../debian/+milestone/3.1
 
 We can change the task's target. Here we change the task's target from
 the mozilla-firefox package to alsa-utils.

=== modified file 'lib/lp/buildmaster/interfaces/buildfarmjobbehavior.py'
--- lib/lp/buildmaster/interfaces/buildfarmjobbehavior.py	2010-01-21 05:03:16 +0000
+++ lib/lp/buildmaster/interfaces/buildfarmjobbehavior.py	2010-03-15 21:11:07 +0000
@@ -1,4 +1,4 @@
-# Copyright 2009 Canonical Ltd.  This software is licensed under the
+# Copyright 2009-2010 Canonical Ltd.  This software is licensed under the
 # GNU Affero General Public License version 3 (see the file LICENSE).
 
 # pylint: disable-msg=E0211,E0213

=== modified file 'lib/lp/buildmaster/model/buildfarmjobbehavior.py'
--- lib/lp/buildmaster/model/buildfarmjobbehavior.py	2010-03-05 13:52:32 +0000
+++ lib/lp/buildmaster/model/buildfarmjobbehavior.py	2010-03-15 21:11:07 +0000
@@ -1,4 +1,4 @@
-# Copyright 2009 Canonical Ltd.  This software is licensed under the
+# Copyright 2009-2010 Canonical Ltd.  This software is licensed under the
 # GNU Affero General Public License version 3 (see the file LICENSE).
 
 # pylint: disable-msg=E0211,E0213
@@ -17,17 +17,22 @@
 import xmlrpclib
 
 from sqlobject import SQLObjectNotFound
+
 from zope.component import getUtility
 from zope.interface import implements
-from zope.security.proxy import removeSecurityProxy
+from zope.security.proxy import removeSecurityProxy, isinstance as zisinstance
 
 from canonical import encoding
 from canonical.librarian.interfaces import ILibrarianClient
+
+from canonical.launchpad.webapp.interfaces import NotFoundError
 from lp.buildmaster.interfaces.builder import CorruptBuildID
 from lp.buildmaster.interfaces.buildfarmjobbehavior import (
     BuildBehaviorMismatch, IBuildFarmJobBehavior)
 from lp.buildmaster.interfaces.buildqueue import IBuildQueueSet
+from lp.buildmaster.model.buildqueue import BuildQueue
 from lp.services.job.interfaces.job import JobStatus
+from lp.soyuz.interfaces.build import IBuildSet
 
 
 class BuildFarmJobBehaviorBase:
@@ -59,22 +64,101 @@
         The default behavior is that we don't add any extra values."""
         return {}
 
+    def _helpVerifyBuildIDComponent(self, raw_id, item_type, finder):
+        """Helper for verifying parts of a `BuildFarmJob` name.
+
+        Different `IBuildFarmJob` implementations can have different
+        ways of constructing their identifying names.  The names are
+        produced by `IBuildFarmJob.getName` and verified by
+        `IBuildFarmJobBehavior.verifySlaveBuildID`.
+
+        This little helper makes it easier to verify an object id
+        embedded in that name, check that it's a valid number, and
+        retrieve the associated database object.
+
+        :param raw_id: An unverified id string as extracted from the
+            build name.  The method will verify that it is a number, and
+            try to retrieve the associated object.
+        :param item_type: The type of object this id represents.  Should
+            be a class.
+        :param finder: A function that, given an integral id, finds the
+            associated object of type `item_type`.
+        :raise CorruptBuildID: If `raw_id` is malformed in some way or
+            the associated `item_type` object is not found.
+        :return: An object that is an instance of `item_type`.
+        """
+        type_name = item_type.__name__
+        try:
+            numeric_id = int(raw_id)
+        except ValueError:
+            raise CorruptBuildID(
+                "%s ID is not a number: '%s'" % (type_name, raw_id))
+
+        try:
+            item = finder(numeric_id)
+        except (NotFoundError, SQLObjectNotFound), reason:
+            raise CorruptBuildID(
+                "%s %d is not available: %s" % (
+                    type_name, numeric_id, reason))
+        except Exception, reason:
+            raise CorruptBuildID(
+                "Error while looking up %s %d: %s" % (
+                    type_name, numeric_id, reason))
+
+        if item is None:
+            raise CorruptBuildID("There is no %s with id %d." % (
+                type_name, numeric_id))
+
+        assert zisinstance(item, item_type), (
+            "Looked for %s, but found %s." % (type_name, repr(item)))
+
+        return item
+
+    def getVerifiedBuild(self, raw_id):
+        """Verify and retrieve the `Build` component of a slave build id.
+
+        This does part of the verification for `verifySlaveBuildID`.
+
+        By default, a `BuildFarmJob` has an identifying name of the form
+        "b-q", where b is the id of its `Build` and q is the id of its
+        `BuildQueue` record.
+
+        Use `getVerifiedBuild` to verify the "b" part, and retrieve the
+        associated `Build`.
+        """
+        # Avoid circular import.
+        from lp.soyuz.model.build import Build
+
+        return self._helpVerifyBuildIDComponent(
+            raw_id, Build, getUtility(IBuildSet).getByBuildID)
+
+    def getVerifiedBuildQueue(self, raw_id):
+        """Verify and retrieve the `BuildQueue` component of a slave build id.
+
+        This does part of the verification for `verifySlaveBuildID`.
+
+        By default, a `BuildFarmJob` has an identifying name of the form
+        "b-q", where b is the id of its `Build` and q is the id of its
+        `BuildQueue` record.
+
+        Use `getVerifiedBuildQueue` to verify the "q" part, and retrieve
+        the associated `BuildQueue` object.
+        """
+        return self._helpVerifyBuildIDComponent(
+            raw_id, BuildQueue, getUtility(IBuildQueueSet).get)
+
     def verifySlaveBuildID(self, slave_build_id):
         """See `IBuildFarmJobBehavior`."""
         # Extract information from the identifier.
         try:
             build_id, queue_item_id = slave_build_id.split('-')
-            build_id = int(build_id)
-            queue_item_id = int(queue_item_id)
         except ValueError:
             raise CorruptBuildID('Malformed build ID')
+            
+        build = self.getVerifiedBuild(build_id)
+        queue_item = self.getVerifiedBuildQueue(queue_item_id)
 
-        try:
-            queue_item = getUtility(IBuildQueueSet).get(queue_item_id)
-            # Check whether build and buildqueue are properly related.
-        except SQLObjectNotFound, reason:
-            raise CorruptBuildID(str(reason))
-        if queue_item.specific_job.build.id != build_id:
+        if build != queue_item.specific_job.build:
             raise CorruptBuildID('Job build entry mismatch')
 
     def updateBuild(self, queueItem):

=== modified file 'lib/lp/buildmaster/tests/test_buildfarmjobbehavior.py'
--- lib/lp/buildmaster/tests/test_buildfarmjobbehavior.py	2010-03-06 04:57:40 +0000
+++ lib/lp/buildmaster/tests/test_buildfarmjobbehavior.py	2010-03-15 21:11:07 +0000
@@ -3,10 +3,18 @@
 
 """Unit tests for BuildFarmJobBehaviorBase."""
 
-from unittest import TestCase, TestLoader
+from unittest import TestLoader
+
+from zope.component import getUtility
+
+from canonical.testing.layers import ZopelessDatabaseLayer
+from lp.testing import TestCaseWithFactory
 
 from lp.buildmaster.interfaces.buildbase import BuildStatus
+from lp.buildmaster.interfaces.builder import CorruptBuildID
 from lp.buildmaster.model.buildfarmjobbehavior import BuildFarmJobBehaviorBase
+from lp.registry.interfaces.pocket import PackagePublishingPocket
+from lp.soyuz.interfaces.processor import IProcessorFamilySet
 
 
 class FakeBuildFarmJob:
@@ -14,27 +22,91 @@
     pass
 
 
-class TestBuildFarmJobBehaviorBase(TestCase):
+class TestBuildFarmJobBehaviorBase(TestCaseWithFactory):
     """Test very small, basic bits of BuildFarmJobBehaviorBase."""
 
-    def setUp(self):
-        self.behavior = BuildFarmJobBehaviorBase(FakeBuildFarmJob())
+    layer = ZopelessDatabaseLayer
+
+    def _makeBehavior(self, buildfarmjob=None):
+        """Create a `BuildFarmJobBehaviorBase`."""
+        if buildfarmjob is None:
+            buildfarmjob = FakeBuildFarmJob()
+        return BuildFarmJobBehaviorBase(buildfarmjob)
+
+    def _makeBuild(self):
+        """Create a `Build` object."""
+        x86 = getUtility(IProcessorFamilySet).getByName('x86')
+        distroarchseries = self.factory.makeDistroArchSeries(
+            architecturetag='x86', processorfamily=x86)
+        distroseries = distroarchseries.distroseries
+        archive = self.factory.makeArchive(
+            distribution=distroseries.distribution)
+        pocket = PackagePublishingPocket.RELEASE
+        spr = self.factory.makeSourcePackageRelease(
+            distroseries=distroseries, archive=archive)
+
+        return spr.createBuild(
+            distroarchseries=distroarchseries, pocket=pocket, archive=archive)
+
+    def _makeBuildQueue(self):
+        """Create a `BuildQueue` object."""
+        return self.factory.makeSourcePackageRecipeBuildJob()
 
     def test_extractBuildStatus_baseline(self):
         # extractBuildStatus picks the name of the build status out of a
         # dict describing the slave's status.
         slave_status = {'build_status': 'BuildStatus.BUILDING'}
+        behavior = self._makeBehavior()
         self.assertEqual(
             BuildStatus.BUILDING.name,
-            self.behavior.extractBuildStatus(slave_status))
+            behavior.extractBuildStatus(slave_status))
 
     def test_extractBuildStatus_malformed(self):
         # extractBuildStatus errors out when the status string is not
         # of the form it expects.
         slave_status = {'build_status': 'BUILDING'}
-        self.assertRaises(
-            AssertionError,
-            self.behavior.extractBuildStatus, slave_status)
+        behavior = self._makeBehavior()
+        self.assertRaises(
+            AssertionError, behavior.extractBuildStatus, slave_status)
+
+    def test_getVerifiedBuild_success(self):
+        build = self._makeBuild()
+        behavior = self._makeBehavior()
+        raw_id = str(build.id)
+
+        self.assertEqual(build, behavior.getVerifiedBuild(raw_id))
+
+    def test_getVerifiedBuild_malformed(self):
+        behavior = self._makeBehavior()
+        self.assertRaises(CorruptBuildID, behavior.getVerifiedBuild, 'hi!')
+
+    def test_getVerifiedBuild_notfound(self):
+        build = self._makeBuild()
+        behavior = self._makeBehavior()
+        nonexistent_id = str(build.id + 99)
+
+        self.assertRaises(
+            CorruptBuildID, behavior.getVerifiedBuild, nonexistent_id)
+
+    def test_getVerifiedBuildQueue_success(self):
+        buildqueue = self._makeBuildQueue()
+        behavior = self._makeBehavior()
+        raw_id = str(buildqueue.id)
+
+        self.assertEqual(buildqueue, behavior.getVerifiedBuildQueue(raw_id))
+
+    def test_getVerifiedBuildQueue_malformed(self):
+        behavior = self._makeBehavior()
+        self.assertRaises(
+            CorruptBuildID, behavior.getVerifiedBuildQueue, 'bye!')
+
+    def test_getVerifiedBuildQueue_notfound(self):
+        buildqueue = self._makeBuildQueue()
+        behavior = self._makeBehavior()
+        nonexistent_id = str(buildqueue.id + 99)
+
+        self.assertRaises(
+            CorruptBuildID, behavior.getVerifiedBuildQueue, nonexistent_id)
 
 
 def test_suite():

=== modified file 'lib/lp/code/model/recipebuilder.py'
--- lib/lp/code/model/recipebuilder.py	2010-02-05 15:06:28 +0000
+++ lib/lp/code/model/recipebuilder.py	2010-03-15 21:11:07 +0000
@@ -8,7 +8,7 @@
     'RecipeBuildBehavior',
     ]
 
-from zope.component import adapts
+from zope.component import adapts, getUtility
 from zope.interface import implements
 
 from lp.archiveuploader.permission import check_upload_to_pocket
@@ -18,7 +18,8 @@
 from lp.buildmaster.model.buildfarmjobbehavior import (
     BuildFarmJobBehaviorBase)
 from lp.code.interfaces.sourcepackagerecipebuild import (
-    ISourcePackageRecipeBuildJob)
+    ISourcePackageRecipeBuildJob, ISourcePackageRecipeBuildSource)
+from lp.code.model.sourcepackagerecipebuild import SourcePackageRecipeBuild
 from lp.registry.interfaces.pocket import PackagePublishingPocket
 from lp.soyuz.adapters.archivedependencies import (
     get_primary_current_component, get_sources_list_for_building)
@@ -168,3 +169,11 @@
                 extra_info['logtail'] = raw_slave_status[2]
 
         return extra_info
+
+    def getVerifiedBuild(self, raw_id):
+        """See `IBuildFarmJobBehavior`."""
+        # This type of job has a build that is of type BuildBase but not
+        # actually a Build.
+        return self._helpVerifyBuildIDComponent(
+            raw_id, SourcePackageRecipeBuild,
+            getUtility(ISourcePackageRecipeBuildSource).getById)

=== removed file 'lib/lp/scripts/utilities/apiindex.py'
--- lib/lp/scripts/utilities/apiindex.py	2009-06-30 16:56:07 +0000
+++ lib/lp/scripts/utilities/apiindex.py	1970-01-01 00:00:00 +0000
@@ -1,21 +0,0 @@
-# Copyright 2009 Canonical Ltd.  This software is licensed under the
-# GNU Affero General Public License version 3 (see the file LICENSE).
-
-"""A script to build reference html from wadl.
-
-Uses an xsl from the launchpadlib package."""
-
-__metaclass__ = type
-__all__ = ['main']
-
-
-import pkg_resources
-import subprocess
-import sys
-
-def main():
-    source = sys.argv[1]
-    stylesheet = pkg_resources.resource_filename(
-        'launchpadlib', 'wadl-to-refhtml.xsl')
-    subprocess.call(['xsltproc', stylesheet, source])
-    pkg_resources.cleanup_resources()

=== modified file 'lib/lp/soyuz/doc/buildd-slavescanner.txt'
--- lib/lp/soyuz/doc/buildd-slavescanner.txt	2010-03-10 12:50:18 +0000
+++ lib/lp/soyuz/doc/buildd-slavescanner.txt	2010-03-15 21:11:07 +0000
@@ -95,15 +95,16 @@
     >>> lostbuilding_builder = MockBuilder(
     ...     'Lost Building Slave', LostBuildingSlave())
     >>> buildergroup.rescueBuilderIfLost(lostbuilding_builder)
-    WARNING:root:Builder 'Lost Building Slave' rescued from
-    '1000-10000': 'Object not found'
+    WARNING:root:Builder 'Lost Building Slave' rescued from '1000-10000':
+    'Build 1000 is not available: 'Object not found''
 
 Then a lost slave in status 'WAITING':
 
     >>> lostwaiting_builder = MockBuilder(
     ...     'Lost Waiting Slave', LostWaitingSlave())
     >>> buildergroup.rescueBuilderIfLost(lostwaiting_builder)
-    WARNING:root:Builder 'Lost Waiting Slave' rescued from '1000-10000': 'Object not found'
+    WARNING:root:Builder 'Lost Waiting Slave' rescued from '1000-10000':
+    'Build 1000 is not available: 'Object not found''
 
 Both got rescued, as expected.
 

=== modified file 'lib/lp/testing/factory.py'
--- lib/lp/testing/factory.py	2010-03-11 20:54:36 +0000
+++ lib/lp/testing/factory.py	2010-03-15 21:11:07 +0000
@@ -2008,6 +2008,81 @@
     def getAnySourcePackageUrgency(self):
         return SourcePackageUrgency.MEDIUM
 
+    def makeSourcePackageRelease(self, archive=None, sourcepackagename=None,
+                                 distroseries=None, maintainer=None,
+                                 creator=None, component=None, section=None,
+                                 urgency=None, version=None,
+                                 builddepends=None, builddependsindep=None,
+                                 build_conflicts=None,
+                                 build_conflicts_indep=None,
+                                 architecturehintlist='all',
+                                 dsc_maintainer_rfc822=None,
+                                 dsc_standards_version='3.6.2',
+                                 dsc_format='1.0', dsc_binaries='foo-bin',
+                                 date_uploaded=UTC_NOW):
+        """Make a `SourcePackageRelease`."""
+        if distroseries is None:
+            if archive is None:
+                distribution = None
+            else:
+                distribution = archive.distribution
+            distroseries = self.makeDistroRelease(distribution=distribution)
+
+        if archive is None:
+            archive = self.makeArchive(
+                distribution=distroseries.distribution,
+                purpose=ArchivePurpose.PRIMARY)
+
+        if sourcepackagename is None:
+            sourcepackagename = self.makeSourcePackageName()
+
+        if component is None:
+            component = self.makeComponent()
+
+        if urgency is None:
+            urgency = self.getAnySourcePackageUrgency()
+
+        if section is None:
+            section = self.getUniqueString('section')
+        section = getUtility(ISectionSet).ensure(section)
+
+        if maintainer is None:
+            maintainer = self.makePerson()
+
+        maintainer_email = '%s <%s>' % (
+            maintainer.displayname,
+            maintainer.preferredemail.email)
+
+        if creator is None:
+            creator = self.makePerson()
+
+        if version is None:
+            version = self.getUniqueString('version')
+
+        return distroseries.createUploadedSourcePackageRelease(
+            sourcepackagename=sourcepackagename,
+            maintainer=maintainer,
+            creator=creator,
+            component=component,
+            section=section,
+            urgency=urgency,
+            version=version,
+            builddepends=builddepends,
+            builddependsindep=builddependsindep,
+            build_conflicts=build_conflicts,
+            build_conflicts_indep=build_conflicts_indep,
+            architecturehintlist=architecturehintlist,
+            changelog_entry=None,
+            dsc=None,
+            copyright=self.getUniqueString(),
+            dscsigningkey=None,
+            dsc_maintainer_rfc822=maintainer_email,
+            dsc_standards_version=dsc_standards_version,
+            dsc_format=dsc_format,
+            dsc_binaries=dsc_binaries,
+            archive=archive,
+            dateuploaded=date_uploaded)
+
     def makeSourcePackagePublishingHistory(self, sourcepackagename=None,
                                            distroseries=None, maintainer=None,
                                            creator=None, component=None,
@@ -2027,54 +2102,31 @@
                                            dsc_format='1.0',
                                            dsc_binaries='foo-bin',
                                            ):
-        if sourcepackagename is None:
-            sourcepackagename = self.makeSourcePackageName()
-        spn = sourcepackagename
-
+        """Make a `SourcePackagePublishingHistory`."""
         if distroseries is None:
-            distroseries = self.makeDistroRelease()
+            if archive is None:
+                distribution = None
+            else:
+                distribution = archive.distribution
+            distroseries = self.makeDistroRelease(distribution=distribution)
 
         if archive is None:
             archive = self.makeArchive(
                 distribution=distroseries.distribution,
                 purpose=ArchivePurpose.PRIMARY)
 
-        if component is None:
-            component = self.makeComponent()
-
         if pocket is None:
             pocket = self.getAnyPocket()
 
         if status is None:
             status = PackagePublishingStatus.PENDING
 
-        if urgency is None:
-            urgency = self.getAnySourcePackageUrgency()
-
-        if section is None:
-            section = self.getUniqueString('section')
-        section = getUtility(ISectionSet).ensure(section)
-
-        if maintainer is None:
-            maintainer = self.makePerson()
-
-        maintainer_email = '%s <%s>' % (
-            maintainer.displayname,
-            maintainer.preferredemail.email)
-
-        if creator is None:
-            creator = self.makePerson()
-
-        if version is None:
-            version = self.getUniqueString('version')
-
-        gpg_key = self.makeGPGKey(creator)
-
-        spr = distroseries.createUploadedSourcePackageRelease(
-            sourcepackagename=spn,
+        spr = self.makeSourcePackageRelease(
+            archive=archive,
+            sourcepackagename=sourcepackagename,
+            distroseries=distroseries,
             maintainer=maintainer,
-            creator=creator,
-            component=component,
+            creator=creator, component=component,
             section=section,
             urgency=urgency,
             version=version,
@@ -2083,15 +2135,10 @@
             build_conflicts=build_conflicts,
             build_conflicts_indep=build_conflicts_indep,
             architecturehintlist=architecturehintlist,
-            changelog_entry=None,
-            dsc=None,
-            copyright=self.getUniqueString(),
-            dscsigningkey=gpg_key,
-            dsc_maintainer_rfc822=maintainer_email,
             dsc_standards_version=dsc_standards_version,
             dsc_format=dsc_format,
             dsc_binaries=dsc_binaries,
-            archive=archive, dateuploaded=date_uploaded)
+            date_uploaded=date_uploaded)
 
         sspph = SourcePackagePublishingHistory(
             distroseries=distroseries,

=== modified file 'lib/lp/translations/doc/translationtemplatesbuildbehavior.txt'
--- lib/lp/translations/doc/translationtemplatesbuildbehavior.txt	2010-03-05 13:52:32 +0000
+++ lib/lp/translations/doc/translationtemplatesbuildbehavior.txt	2010-03-15 21:11:07 +0000
@@ -2,13 +2,21 @@
 
 == Setup ==
 
-Set up build environment.
+Set up build environment.  Clear out the build queue.
 
     >>> import transaction
     >>> import logging
     >>> logger = logging.getLogger()
     >>> logger.setLevel(logging.CRITICAL)
 
+    >>> from canonical.database.sqlbase import quote
+    >>> from canonical.launchpad.interfaces.lpstorm import IMasterStore
+    >>> from lp.services.job.interfaces.job import JobStatus
+    >>> from lp.services.job.model.job import Job
+    >>> store = IMasterStore(Job)
+    >>> query = store.execute("UPDATE Job SET status = %s" % quote(
+    ...     JobStatus.FAILED))
+
     >>> from lp.buildmaster.master import BuilddMaster
     >>> from canonical.buildd.tests import BuilddSlaveTestSetup
     >>> bm = BuilddMaster(logger, transaction)
@@ -39,7 +47,21 @@
 
 Make a builder to process our build request.
 
-    >>> builder = factory.makeBuilder(virtualized=False, processor=processor)
+    >>> builder = factory.makeBuilder(
+    ...     virtualized=True, processor=processor, vm_host='hostname')
+
+The builder doesn't talk to a real slave.  We don't have those in our
+test suite.  But we give it a fake one.
+
+    >>> from lp.testing.fakemethod import FakeMethod
+    >>> class FakeSlave:
+    ...     build = FakeMethod()
+    ...     cacheFile = FakeMethod()
+    ...     resume = FakeMethod(result=('Output here', 'Errors here', 0))
+
+    >>> from zope.security.proxy import removeSecurityProxy
+    >>> slave = FakeSlave()
+    >>> removeSecurityProxy(builder).slave = slave
 
 
 == Get a job! ==
@@ -60,20 +82,27 @@
     >>> print buildqueue.date_started
     None
 
-Dispatch the job to the build slave.  The proper method to call here
-would have been Builder.findAndStartJob, but it has not been generalised
-to handle new job types yet.
-
-# XXX JeroenVermeulen bug=506617: call findAndStartJob instead.
-
-    >>> from zope.security.proxy import removeSecurityProxy
-    >>> removeSecurityProxy(builder)._dispatchBuildCandidate(buildqueue)
-
-The build is now marked as started.
+Our job is now first in line to be executed.
+
+    >>> removeSecurityProxy(builder)._findBuildCandidate() == buildqueue
+    True
+
+Dispatch the first job in line (ours!) to the build slave.
+
+    >>> activated_job = builder.findAndStartJob()
+    >>> activated_job == buildqueue
+    True
+
+Our build is now marked as started.
 
     >>> buildqueue.date_started is None
     False
 
+The slave's build method has been called.
+
+    >>> slave.build.call_count
+    1
+
 
 == Teardown ==
 

=== modified file 'lib/lp/translations/model/translationtemplatesbuildbehavior.py'
--- lib/lp/translations/model/translationtemplatesbuildbehavior.py	2010-02-11 19:11:11 +0000
+++ lib/lp/translations/model/translationtemplatesbuildbehavior.py	2010-03-15 21:11:07 +0000
@@ -17,6 +17,7 @@
 
 from canonical.launchpad.interfaces import ILaunchpadCelebrities
 
+from lp.buildmaster.interfaces.builder import CorruptBuildID
 from lp.buildmaster.interfaces.buildfarmjobbehavior import (
     IBuildFarmJobBehavior)
 from lp.buildmaster.model.buildfarmjobbehavior import (
@@ -40,12 +41,27 @@
         self._builder.slave.cacheFile(logger, chroot)
         buildid = self.buildfarmjob.getName()
 
-        args = { 'branch_url': self.buildfarmjob.branch.url }
+        args = self.buildfarmjob.metadata
         filemap = {}
 
         self._builder.slave.build(
             buildid, self.build_type, chroot_sha1, filemap, args)
 
+    def verifySlaveBuildID(self, slave_build_id):
+        """See `IBuildFarmJobBehavior`."""
+        try:
+            branch_name, queue_item_id = slave_build_id.rsplit('-', 1)
+        except ValueError:
+            raise CorruptBuildID(
+                "Malformed translation templates build id: '%s'" % (
+                    slave_build_id))
+
+        buildqueue = self.getVerifiedBuildQueue(queue_item_id)
+        if buildqueue.job != self.buildfarmjob.job:
+            raise CorruptBuildID(
+                "ID mismatch for translation templates build '%s'" % (
+                    slave_build_id))
+
     def _getChroot(self):
         ubuntu = getUtility(ILaunchpadCelebrities).ubuntu
         return ubuntu.currentseries.nominatedarchindep.getChroot()

=== modified file 'lib/lp/translations/tests/test_translationtemplatesbuildbehavior.py'
--- lib/lp/translations/tests/test_translationtemplatesbuildbehavior.py	2010-03-12 08:31:43 +0000
+++ lib/lp/translations/tests/test_translationtemplatesbuildbehavior.py	2010-03-15 21:11:07 +0000
@@ -19,6 +19,7 @@
 from lp.buildmaster.interfaces.buildbase import BuildStatus
 from lp.buildmaster.interfaces.buildfarmjobbehavior import (
     IBuildFarmJobBehavior)
+from lp.buildmaster.interfaces.builder import CorruptBuildID
 from lp.buildmaster.interfaces.buildqueue import IBuildQueueSet
 from lp.testing import TestCaseWithFactory
 from lp.testing.fakemethod import FakeMethod
@@ -123,6 +124,10 @@
         self.assertEqual(
             'translation-templates', slave_status['test_build_type'])
         self.assertIn('branch_url', slave_status['test_build_args'])
+        # The slave receives the public http URL for the branch.
+        self.assertEqual(
+            behavior.buildfarmjob.branch.composePublicURL(),
+            slave_status['test_build_args']['branch_url'])
 
     def test_getChroot(self):
         # _getChroot produces the current chroot for the current Ubuntu
@@ -170,6 +175,38 @@
         self.assertEqual(1, builder.cleanSlave.call_count)
         self.assertEqual(0, behavior._uploadTarball.call_count)
 
+    def test_verifySlaveBuildID_success(self):
+        # TranslationTemplatesBuildJob.getName generates slave build ids
+        # that TranslationTemplatesBuildBehavior.verifySlaveBuildID
+        # accepts.
+        behavior = self._makeBehavior()
+        buildfarmjob = behavior.buildfarmjob
+        job = buildfarmjob.job
+
+        # The test is that this not raise CorruptBuildID (or anything
+        # else, for that matter).
+        behavior.verifySlaveBuildID(behavior.buildfarmjob.getName())
+
+    def test_verifySlaveBuildID_handles_dashes(self):
+        # TranslationTemplatesBuildBehavior.verifySlaveBuildID can deal
+        # with dashes in branch names.
+        behavior = self._makeBehavior()
+        buildfarmjob = behavior.buildfarmjob
+        job = buildfarmjob.job
+        buildfarmjob.branch.name = 'x-y-z--'
+
+        # The test is that this not raise CorruptBuildID (or anything
+        # else, for that matter).
+        behavior.verifySlaveBuildID(behavior.buildfarmjob.getName())
+
+    def test_verifySlaveBuildID_malformed(self):
+        behavior = self._makeBehavior()
+        self.assertRaises(CorruptBuildID, behavior.verifySlaveBuildID, 'huh?')
+
+    def test_verifySlaveBuildID_notfound(self):
+        behavior = self._makeBehavior()
+        self.assertRaises(CorruptBuildID, behavior.verifySlaveBuildID, '1-1')
+
 
 def test_suite():
     return TestLoader().loadTestsFromName(__name__)

=== added file 'utilities/apidoc-index.pt'
--- utilities/apidoc-index.pt	1970-01-01 00:00:00 +0000
+++ utilities/apidoc-index.pt	2010-03-15 21:11:07 +0000
@@ -0,0 +1,37 @@
+<html
+  xmlns="http://www.w3.org/1999/xhtml"
+  xmlns:tal="http://xml.zope.org/namespaces/tal"
+  xmlns:metal="http://xml.zope.org/namespaces/metal"
+  xmlns:i18n="http://xml.zope.org/namespaces/i18n"
+  i18n:domain="launchpad"
+>
+  <head>
+    <title>Launchpad Web Service API</title>
+  </head>
+
+  <body>
+
+    <h1>Launchpad web service API documentation</h1>
+
+    <p tal:content="structure config/service_description">
+      Description of the Launchpad web service.
+    </p>
+
+    <h2>Active versions</h2>
+
+    <ul>
+      <li tal:repeat="version_and_description versions_and_descriptions">
+
+        <tal:version tal:define="version version_and_description/version;
+                         description version_and_description/description">
+
+        <a tal:attributes="href string:$version.html"
+           tal:content="version">Version name</a>:
+        <tal:description replace="description" />
+        </tal:version>
+      </li>
+    </ul>
+
+  </body>
+
+</html>

=== renamed file 'utilities/create-lp-wadl.py' => 'utilities/create-lp-wadl-and-apidoc.py'
--- utilities/create-lp-wadl.py	2010-03-01 21:16:06 +0000
+++ utilities/create-lp-wadl-and-apidoc.py	2010-03-15 21:11:07 +0000
@@ -12,10 +12,15 @@
 
 import _pythonpath
 
+from cStringIO import StringIO
+import os
+import pkg_resources
+import subprocess
 import sys
 import urlparse
 
 from zope.component import getUtility
+from zope.pagetemplate.pagetemplatefile import PageTemplateFile
 
 from canonical.launchpad.ftests import login, ANONYMOUS
 from canonical.launchpad.scripts import execute_zcml_for_scripts
@@ -30,6 +35,9 @@
     execute_zcml_for_scripts()
     config = getUtility(IWebServiceConfiguration)
 
+    stylesheet = pkg_resources.resource_filename(
+        'launchpadlib', 'wadl-to-refhtml.xsl')
+
     # Request the WADL from the root resource.
     # We do this by creating a request object asking for a WADL
     # representation.
@@ -52,6 +60,33 @@
         content = request.publication.getApplication(request)(request)
         f.write(content)
         f.close()
+
+        # Now, convert the WADL into an human-readable description and
+        # put the HTML in the same directory as the WADL.
+        directory, ignore = os.path.split(path_template)
+        html_filename = os.path.join(directory, version + ".html")
+        print "Writing apidoc for version %s to %s" % (
+            version, html_filename)
+        stdout = open(html_filename, "w")
+        subprocess.Popen(['xsltproc', stylesheet, filename], stdout=stdout)
+        stdout.close()
+
+    # Finally, create an index.html with links to all the HTML
+    # documentation files we just generated.
+    template_file = 'apidoc-index.pt'
+    template = PageTemplateFile(template_file)
+    namespace = template.pt_getContext()
+    namespace['config'] = config
+    versions_and_descriptions = []
+    for version in config.active_versions:
+        versions_and_descriptions.append(
+            dict(version=version,
+                 description=config.version_descriptions[version]))
+    namespace['versions_and_descriptions'] = versions_and_descriptions
+
+    f = open(os.path.join(directory, "index.html"), 'w')
+    f.write(template.pt_render(namespace))
+
     return 0
 
 if __name__ == '__main__':

=== modified file 'versions.cfg'
--- versions.cfg	2010-03-08 22:26:29 +0000
+++ versions.cfg	2010-03-15 21:11:07 +0000
@@ -21,15 +21,15 @@
 grokcore.component = 1.6
 httplib2 = 0.6.0
 ipython = 0.9.1
-launchpadlib = 1.5.5
+launchpadlib = 1.5.6
 lazr.authentication = 0.1.1
 lazr.batchnavigator = 1.1
 lazr.config = 1.1.3
 lazr.delegates = 1.1.0
 lazr.enum = 1.1.2
 lazr.lifecycle = 1.1
-lazr.restful = 0.9.21
-lazr.restfulclient = 0.9.11
+lazr.restful = 0.9.23
+lazr.restfulclient = 0.9.12
 lazr.smtptest = 1.1
 lazr.testing = 0.1.1
 lazr.uri = 1.0.2