Re: Path troubles when using SPHINXDIRS option

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 21 Apr 2020 10:38:14 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Hi,
> 
> While building from v5.7-rc2 + media, I noticed that SPHINXDIRS option
> stopped working.
> 
> What happens is that, if we don't pass this option, Sphinx assumes that
> the "absolute" path is "Documentation/". So, include options like this:
> 
> 	.. include:: /ABI/stable/firewire-cdev
> 	    :literal:
> 
> 
> would be evaluated as Documentation/ABI/stable/firewire-cdev if built
> without SPHINXDIRS. However, if we do SPHINXDIRS=driver-api, then
> the "absolute" patch would be "Documentation/driver-api", causing this
> error:
> 
> 	Sphinx parallel build error:
> 	docutils.utils.SystemMessage: /devel/v4l/patchwork/Documentation/driver-api/firewire.rst:22: (SEVERE/4) Problems with "include" directive path:
> 
> This is specially bad for build jobs (like one we have on jenkins that
> is meant to test media patches), as, due to some Sphinx bug, prevents
> sphinx-build to stop, making the toolset to run forever.
> 
> I suspect that some change at conf.py could address the path issue.
> 
> I'll try to investigate further.

More updates on it:

It seems that the main issue is that Sphinx passes Documentation/foo
to docutils, when SPHINXDIRS=foo is used, and docutils prevent
access anything outside Documentation/foo on its include and toctree
directives.

So, even trying to use "../ABI/some_doc" would fail.

-

The other issue is that SphinxParallelError doesn't stop the
build multithreading tasks. As Documentation/docutils.conf is set to 
abort on severe errors, this causes Sphinx to keep running forever,
doing nothing.

I did already a workaround to prevent media Jenkins job to hang
due to those issues. So, I'm moving on. Hopefully, someone with
more experience with Sphinx, docutils and python multithreading
can work on some fixes for it.

Thanks,
Mauro