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

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

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?

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

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

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.