[Pulp-list] v2 REST API Documentation Early Look

[Jay Dobies]

> 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.

That's where I hit it most, using autodoc. I suppose I just got in the 
habit without remembering why.

> 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.

So glad you brought this up now. This is exactly the sort of thing I 
wanted to have nailed down before we really started down the path. I'll 
take a look this morning, thanks  :)


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