On Tue, 2018-04-03 at 12:04 -0400, Zane Bitter wrote: > On 03/04/18 06:28, Stephen Finucane wrote: > > On Mon, 2018-04-02 at 19:41 -0400, Zane Bitter wrote: > > > On 28/03/18 10:31, Stephen Finucane wrote: > > > > As noted last week [1], we're trying to move away from pbr's autodoc > > > > feature as part of the new docs PTI. To that end, I've created > > > > sphinxcontrib-apidoc, which should do what pbr was previously doing for > > > > us by via a Sphinx extension. > > > > > > > > https://pypi.org/project/sphinxcontrib-apidoc/ > > > > > > > > This works by reading some configuration from your documentation's > > > > 'conf.py' file and using this to call 'sphinx-apidoc'. It means we no > > > > longer need pbr to do this for. > > > > > > > > I have pushed version 0.1.0 to PyPi already but before I add this to > > > > global requirements, I'd like to ensure things are working as expected. > > > > smcginnis was kind enough to test this out on glance and it seemed to > > > > work for him but I'd appreciate additional data points. The > > > > configuration steps for this extension are provided in the above link. > > > > To test this yourself, you simply need to do the following: > > > > > > > > 1. Add 'sphinxcontrib-apidoc' to your test-requirements.txt or > > > > doc/requirements.txt file > > > > 2. Configure as noted above and remove the '[pbr]' and > > > > '[build_sphinx]' > > > > configuration from 'setup.cfg' > > > > 3. Replace 'python setup.py build_sphinx' with a call to > > > > 'sphinx-build' > > > > 4. Run 'tox -e docs' > > > > 5. Profit? > > > > > > > > Be sure to let me know if anyone encounters issues. If not, I'll be > > > > pushing for this to be included in global requirements so we can start > > > > the migration. > > > > > > Thanks Stephen! I tried it out with no problems: > > > > > > https://review.openstack.org/558262 > > > > > > However, there are a couple of differences compared to how pbr did things. > > > > > > 1) pbr can generate an 'autoindex' file with a flat list of modules > > > (this appears to be configurable with the autodoc_index_modules option), > > > but apidoc only generates a 'modules' file with a hierarchical list of > > > modules. This is easy to work around, but I guess it needs to be added > > > to the instructions to check that you're not relying on it. > > > > Yup, smcginnis and I discussed this at some point. PBR has two > > different ways of generating API documentation: 'autodoc_tree', which > > is based on 'sphinx-apidoc', and 'autodoc', which is custom (and > > presumably legacy). This extension replaces the former of those but, as > > you note below, it seems 'sphinx-apidoc' can be wrangled into > > generating something approaching the latter. > > That explains quite a lot that was confusing me :D > > > > 2) pbr generates a page per module; this plugin generates a page per > > > package. This results in waaaay too much information on a page to be > > > able to navigate it comfortably IMHO. To the point where it's easier to > > > read the code. (It also breaks existing links, if you care about that > > > kind of thing.) I sent you a PR to add an option to pass --separate: > > > > > > https://github.com/sphinx-contrib/apidoc/pull/1 > > > > Thanks for that. I've merged it and will use it as the basis of a 0.2.0 > > release assuming nothing else pops up in the next day or two. > > Thanks! > > > I'm not sure what we can do about the broken links though - maybe use the > > redirect infrastructure to just send everyone to the new place? I guess > > I can add this to the guide I'm adding to the README on migrating from > > pbr. > > No links break if you use the apidoc_separate_modules=True option, so I > would recommend any projects currently generating a page per module > (i.e. using 'autodoc' instead of 'autodoc_tree') should enable that > option to keep continuity.
Fancy taking a look at [1], in that case? This should clarify everything. [1] https://github.com/sphinx-contrib/apidoc/pull/3 Stephen __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev