[Pulp-list] v2 REST API Documentation Early Look
Jay Dobies
jason.dobies at redhat.com
Tue Mar 27 20:30:56 UTC 2012
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
More information about the Pulp-list
mailing list