Open Stack

On Thu, 2018-03-29 at 07:47 -0500, Sean McGinnis wrote:
> > > 
> > > It's not mentioned here, but I discovered today that Cinder is using the
> > > sphinx.ext.autodoc module. Is there any issue with using this?
> > > 
> > 
> > Nope - sphinx-apidoc and the likes use autodoc under the hood. You can
> > see this by checking the output in 'contributor/api' or the likes.
> > 
> > Stephen
> > 
> 
> I'm wondering if there is a problem with using this vs. the way being proposed.
> 
> In other words, do we need to switch over to this new sphinxcontrib module, or
> staying with autodoc should be OK. And if so, why not switch current users of
> the pbr method over to use sphinx.ext.autdoc rather than introducing something
> new?

tl;dr: You don't _have_ to automate this stuff, but it helps.

sphinx-apidoc generates stub files containing a whole load of autodoc
directives. As noted above, you can check the output of a sphinx-apidoc 
run and you'll see just this. If I were to guess, Cinder simply checked
in the output of such a run [*] into Git, meaning they don't need to
run it each time. This works but it comes with the downside that your
docs can and will get out of sync with the actual code when, for
example, you either add or remove some modules or functions. Running
sphinx-apidoc on each build, as we've been doing with pbr's autodoc
feature, ensures this out-of-sync issue doesn't happen, at the expense
of increased doc build times.

Stephen

[*] They might also have handwritten this stuff, but I highly doubt
that (it's rather tedious to write).