Ubuntu Wiki

Currently used tools for generating API documentation:

Gtk-doc

• For GObject-based APIs

Doxygen

• For C++-based APIs (currently the Qt ones and Nux)

lazr.restful TALES templates, WADL sitemaps and XSLT

• For the Launchpad API documentation

How is the Launchpad API documentation published

(info from Leonard Richardson)

The human-readable web service documentation ultimately flows from the Launchpad code that implements the web service, and the docstrings associated with that code.

Take a specific example: the name of a bug. That's defined as IBug.name in lib/lp/bugs/interfaces/bugs.py.

Here's the code:

     name = exported(
         BugNameField(
             title=_('Nickname'), required=False,
             description=_("""A short and unique name.
                 Add one only if you often need to retype the URL
                 but have trouble remembering the bug number."""),

lazr.restful uses a TALES template to generate a WADL "site map" which includes <doc> tags containing every bit of human-readable documentation obtainable from the docstrings. Here's the relevant part of the TALES template, from lazr.restful src/lazr/restful/templates/wadl-root.pt:

<wadl:doc tal:replace="structure field/wadl:doc">
                 Field description
</wadl:doc>

(field/wadl:doc refers to a utility function that turns the field's docstring into HTML.)

The WADL document also includes non-human-readable metadata about the web service, such as which fields are writable.

The WADL site map is used by launchpadlib to interactively navigate the web service, but it's also the source of the HTML documentation. We use an XSLT stylesheet for this: going back to Launchpad, it's in lib/lp/services/webservice/wadl-to-refhtml.xsl.

The XSLT stylesheet extracts all the HTML from the <doc> tags and assembles them into a web page. The HTML documentation has the same structure as the WADL document.

Which is how you get HTML markup like this:

<td>
<p>
<strong>name</strong>
</p>
</td>
<td>
<p>
<small>(writeable)</small>
</p>
</td>
<td>
<div>
<p>Nickname</p>
<dlclass="rst-docutils">
<dt>A short and unique name.</dt>
<dd>Add one only if you often need to retype the URL
but have trouble remembering the bug number.</dd>
</dl>

</div>
</td>