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

[Pulp-list] v2 REST API Documentation Early Look

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:

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

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