Open Stack

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.