On Wed, 2018-03-28 at 15:31 +0100, 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. > > Cheers, > Stephen > > [1] http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html
'sphinxcontrib.apidoc' has now been added to requirements [1]. The README [2] provides a far more detailed overview of how one can migrate from the pbr features than I gave above and I'd advise anyone making changes to their documentation to follow that guide. Feel free to ping me here or on IRC (stephenfin) if you've any questions. Next up: deprecating this feature in pbr. Stephen [1] https://review.openstack.org/#/c/557532/ [2] https://github.com/sphinx-contrib/apidoc#migration-from-pbr __________________________________________________________________________ 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