Open Stack

On 03/22/2018 05:43 AM, Stephen Finucane wrote:
> On Wed, 2018-03-21 at 09:57 -0500, Sean McGinnis wrote:
>> On Wed, Mar 21, 2018 at 10:49:02AM +0000, Stephen Finucane wrote:
>>> tl;dr: Make sure you stop using pbr's autodoc feature before converting
>>> them to the new PTI for docs.
>>>
>>> [snip]
>>>
>>> I've gone through and proposed a couple of reverts to fix projects
>>> we've already broken. However, going forward, there are two things
>>> people should do to prevent issues like this popping up.
>>
>> Unfortunately this will not work to just revert the changes. That may fix
>> things locally, but they will not pass in gate by going back to the old way.
>>
>> Any cases of this will have to actually be updated to not use the unsupported
>> pieces you point out. But the doc builds will still need to be done the way
>> they are now, as that is what the PTI requires at this point.
> 
> That's unfortunate. What we really need is a migration path from the
> 'pbr' way of doing things to something else. I see three possible
> avenues at this point in time:
> 
>     1. Start using 'sphinx.ext.autosummary'. Apparently this can do similar
>        things to 'sphinx-apidoc' but it takes the form of an extension.
>        From my brief experiments, the output generated from this is
>        radically different and far less comprehensive than what 'sphinx-
>        apidoc' generates. However, it supports templating so we could
>        probably configure this somehow and add our own special directive
>        somewhere like 'openstackdocstheme'
>     2. Push for the 'sphinx.ext.apidoc' extension I proposed some time back
>        against upstream Sphinx [1]. This essentially does what the PBR
>        extension does but moves configuration into 'conf.py'. However, this
>        is currently held up as I can't adequately explain the differences
>        between this and 'sphinx.ext.autosummary' (there's definite overlap
>        but I don't understand 'autosummary' well enough to compare them).
>     3. Modify the upstream jobs that detect the pbr integration and have
>        them run 'sphinx-apidoc' before 'sphinx-build'. This is the least
>        technically appealing approach as it still leaves us unable to build
>        stuff locally and adds yet more "magic" to the gate, but it does let
>        us progress.

I'd suggest a #4:

Take the sphinx.ext.apidoc extension and make it a standalone extension 
people can add to doc/requirements.txt and conf.py. That way we don't 
have to convince the sphinx folks to land it.

I'd been thinking for a while "we should just write a sphinx extension 
with the pbr logic in it" - but hadn't gotten around to doing anything 
about it. If you've already written that extension - I think we're in 
potentially great shape!

> Try as I may, I don't really have the bandwidth to work on this for
> another few weeks so I'd appreciate help from anyone with sufficient
> Sphinx-fu to come up with a long-term solution to this issue.



> Cheers,
> Stephen
> 
> [1] https://github.com/sphinx-doc/sphinx/pull/4101/files
> 
>>>   * Firstly, you should remove the '[build_sphinx]' and '[pbr]' sections
>>>     from 'setup.cfg' in any patches that aim to convert a project to use
>>>     the new PTI. This will ensure the gate catches any potential
>>>     issues.
>>>   * In addition, if your project uses the pbr autodoc feature, you
>>>     should either (a) remove these docs from your documentation tree or
>>>     (b) migrate to something else like the 'sphinx.ext.autosummary'
>>>     extension [5]. I aim to post instructions on the latter shortly.
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>