[openstack-dev] Following the new PTI for document build, broken local builds
sfinucan at redhat.com
Fri Mar 23 17:25:42 UTC 2018
On Fri, 2018-03-23 at 12:23 -0400, Doug Hellmann wrote:
> Excerpts from Monty Taylor's message of 2018-03-23 08:03:22 -0500:
> > On 03/22/2018 05:43 AM, Stephen Finucane wrote:
> > >
> > > 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 . 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!
> That also has the benefit that we don't have to wait for a new sphinx
> release to start using it.
I can do this. Where will it live? pbr? openstackdocstheme? Somewhere
More information about the OpenStack-dev