Open Stack

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
>     updates.
>     
>     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.

Doug