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). __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
