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

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



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


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