Launchpad itself

Code review comment for lp:~leonardr/launchpad/multiversion-apidoc

multiversion-apidoc
Merge into db-devel

Revision history for this message

Leonard Richardson (leonardr) wrote on 2010-03-15:

#

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?

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?

« Back to merge proposal