[Pulp-list] v2 REST API Documentation Early Look

[Jay Dobies]

I have a task this sprint to set us up so we can write REST API docs now 
instead of scrambling at the last minute. The most recent time we 
investigated moving to sphinx it didn't make sense; we had too many docs 
already in wiki format and not enough time.

In v2, we're going to have to rewrite a good 95% of the docs as the APIs 
are changing, so it makes more sense to look into sphinx now.

Here's a quick preview:
http://jdob.fedorapeople.org/pulp-api/

Don't look for accuracy; I ported the repo APIs that I wrote a few 
months ago and are, in some places, flat out wrong. Success response, 
for instance, is singular and doesn't mention where a 202 might return.

But do let me know what you think about the format of the individual API 
calls themselves. I haven't put too much thought into it yet and only 
started on porting the repo APIs as a trial run.

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.

If you're curious to play around, here's the really quick version:

* Install sphinx (use easy_install)
* Go into <git root>/docs/sphinx/rest-api
* Run "make clean && make html"
  * You'll want to run clean every time, I've had it not pick up changes 
with annoying regularity and, frankly, it's fast.
* Built site is under docs/sphinx/rest-api/_build/html

Feel free to ping me with comments.

-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org