[Pulp-list] v2 REST API Documentation Early Look

[Nick Coghlan]

On 03/28/2012 10:29 PM, Jay Dobies wrote:
>> 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.

Yeah, there's a problem where Sphinx only looks at which *doc* files 
have changed since the last docs build, so it has no idea if any of the 
source files that autodoc relies on has changed (since that connection 
is mediated by Python's import system).

As something of tangent, I just discovered sphinx-apidoc, which may be 
useful for generating developer API reference docs:
http://sphinx.pocoo.org/man/sphinx-apidoc.html (Sphinx 1.1)
https://bitbucket.org/etienned/sphinx-autopackage-script/src (earlier 
versions)

Cheers,
Nick.

-- 
Nick Coghlan
Red Hat Engineering Operations, Brisbane