Open Stack

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

Ah, perfect. This was the motivation I was looking for. I don't think anyone on
the team is aware of this. In this case, switching over to using the new,
dynamically generated way has a lot of benefit.

Looking deeper, there are some custom things being done to generate this
output. So rather than maintaining (or really not maintaining as is the reality
here) this custom code, we should streamline this and be consistent by
following the new approach.