[Pulp-list] v2 REST API Documentation Early Look

[Nick Coghlan]

On 03/28/2012 06:30 AM, Jay Dobies wrote:
> I'll do an overview of sphinx, the syntax, and what I'm suggesting for
> the format for our calls in second part of Thursday's deep dive. I'll
> give my full impressions then, but the short answer is that once you
> start to understand it, it's kinda fun and looks pretty solid. I'd be
> surprised if we found reasons not to continue down this path.

One feature of Sphinx that I particularly love is the service at 
www.readthedocs.org - set up a project over there, set up your 
post-commit hook or a cron job and you have a website with nice looking 
docs ready to go. Very handy for projects that don't have any web 
infrastructure of their own set up yet.

> If you're curious to play around, here's the really quick version:
>
> * Install sphinx (use easy_install)

"pip install sphinx" or "yum install python-sphinx" are probably better 
options. (There are a few things about the way easy_install works that 
mean it doesn't always play well with others - "pip" is the preferred 
replacement for direct installation from PyPI. For anyone running Fedora 
though, the version in the Fedora repos should be sufficiently recent)

> * You'll want to run clean every time, I've had it not pick up changes
> with annoying regularity and, frankly, it's fast.

Hmm, that shouldn't happen for the ordinary ReST files. It can 
definitely be a problem when using extensions like autodoc, though. 
Still, as you say, rebuilding from scratch is generally pretty fast.

Before you do too far down the path of converting to Sphinx, you may 
want to investigate implementing some custom directives and roles, since 
it's a lot easier to use those from the start than it is to retrofit 
them later.

For example, rather than the current manually formatted list of bullet 
points which has no semantic markup, it may instead make sense to write 
something like:

.. rest_api: Create Repository
    :method: POST
    :path: /v2/repositories
    :permission: create
    .. rest_param:: id
       :type: str
       unique identifier for the repository
    .. rest_param:: display_name
       :type: str
       :optional:
       user-friendly name for the repository
    .. rest_param:: description
       :type: str
       :optional:
       user-friendly text describing the repository's contents
    .. rest_param:: notes
       :type: dict
       :optional:
       key-value pairs to programmatically tag the repository
    .. success:: 201
       database representation of the created repository
    .. failure:: 409
       there is already a repository with the given ID
    .. failure:: 400
       one or more of the supplied parameters is invalid


There are a few advantages to using a custom directive like this:
- you can also define a rest_call role that would let you write 
:rest_call:`Create Repository` and it would create a hyperlink for you 
to the appropriate rest_api definition.
- you can define the formatting for the directive *once* and then all 
directives will follow it, instead of having to keep the formatting 
consistent manually
- you can define indices and tables that summarise all instances of a 
particular directive (e.g. the module index and the full index in Python 
are generated that way)

There's a tutorial on creating custom extensions in the Sphinx docs:
http://sphinx.pocoo.org/ext/tutorial.html

Cheers,
Nick.

-- 
Nick Coghlan
Red Hat Engineering Operations, Brisbane