[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [Pulp-list] v2 REST API Documentation Early Look



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]