[openstack-dev] [docs][neutron] checking link integrity in the gate
doug at doughellmann.com
Wed Sep 6 18:46:54 UTC 2017
Excerpts from Alexandra Settle's message of 2017-09-06 17:47:44 +0000:
> On 9/6/17, 12:10 PM, "Doug Hellmann" <doug at doughellmann.com> wrote:
> Excerpts from Doug Hellmann's message of 2017-09-05 13:53:40 -0400:
> > Excerpts from Boden Russell's message of 2017-09-05 11:25:34 -0600:
> > >
> > > On 9/5/17 11:03 AM, Doug Hellmann wrote:
> > > > Is eventlet being initialized (or partially initialized) when a module
> > > > from the application is imported for the auto-generated API
> > > > documentation?
> > > More than likely :)
> > > But even if they are, what's the fix/workaround?
> > >
> > Ensure that it is fully initialized, or not initialized at all, I would
> > think. I'm sure Sphinx does not expect to be running under eventlet.
> > I see a comment in neutron's doc/source/conf.py about another issue with
> > eventlet and some of the test code. I would start by configuring pbr to
> > ignore the test code when generating class documentation and see if that
> > eliminates both problems. See "autodoc_tree_excludes" in
> > https://docs.openstack.org/pbr/latest/user/using.html#pbr for details.
> > If that doesn't help, then I would try to find a way to avoid
> > initializing eventlet at all. For example, set an environment variable
> > in doc/source/conf.py and then look for it in
> > neutron/common/eventlet_utils.py and skip the call to
> > eventlet.monkey_patch().
> > If neither of those options work, we can continue thinking of other
> > ideas.
> > Doug
> Something to watch out for when using link check in CI: It's a path for
> someone outside of your team to break your gate, just by renaming a web
> page. It might be more useful to schedule regular manual runs and
> The docs team may have suggestions for how they handle that on the main
> docs.o.o site and the guides they manage.
> Previously we have run a spider over our repo. Specifically, I know Andreas has successfully used https://github.com/alecxe/broken-links-checker.git
> Hopefully this helps. I was thinking we needed to do the same thing over the manuals repo now we have finalized most of the migration.
To be clear, if you can get Sphinx's linkchecker builder to work, that's
a great option for this. I just don't think you really want to run it
for every check or gate job that builds the docs.
More information about the OpenStack-dev