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.
cheers,
Zane.
__________________________________________________________________________
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
