Em Tue, 21 Apr 2020 10:38:14 +0200 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
