1. Patchew
  2. QEMU
  3. View series

[PATCH] docs: fix sphinx build failure

Pierrick Bouvier posted 1 patch 4 days, 11 hours ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20260720222717.33078-1-pierrick.bouvier@oss.qualcomm.com
Maintainers: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
There is a newer version of this series
docs/meson.build | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
[PATCH] docs: fix sphinx build failure
Posted by Pierrick Bouvier 4 days, 11 hours ago 
We recently started to have those failures appearing when building
documentation. It's hard to identify if it comes from a python, sphinx
or sphinx extension, but it blocks us.

Exception occurred:
  File "/usr/lib/python3.13/multiprocessing/connection.py", line 399, in _recv
    raise EOFError
EOFError
The full traceback has been saved in /tmp/sphinx-*.log, if you want to report the issue to the developers.

This seems to be the generic error message for "something went wrong in
sphinx multiprocess":
- https://github.com/sphinx-doc/sphinx/issues/11449
- https://github.com/sphinx-doc/sphinx/issues/14458
- https://github.com/sphinx-doc/sphinx/issues/8973

Solve the issue by simply going back to sequential builds. We didn't
notice a huge speedup anyway.

Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
---
 docs/meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/meson.build b/docs/meson.build
index a8d893681ec..4d8cc545fcc 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -4,7 +4,7 @@ sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build',
 # Check if tools are available to build documentation.
 build_docs = false
 if sphinx_build.found()
-  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q', '-j', 'auto']
+  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q']
   # If we're making warnings fatal, apply this to Sphinx runs as well
   if get_option('werror')
     SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
-- 
2.43.0
Re: [PATCH] docs: fix sphinx build failure
Posted by Michael Tokarev 3 days, 16 hours ago 
On 7/21/26 01:27, Pierrick Bouvier wrote:
> We recently started to have those failures appearing when building
> documentation. It's hard to identify if it comes from a python, sphinx
> or sphinx extension, but it blocks us.
> 
> Exception occurred:
>    File "/usr/lib/python3.13/multiprocessing/connection.py", line 399, in _recv
>      raise EOFError
> EOFError
> The full traceback has been saved in /tmp/sphinx-*.log, if you want to report the issue to the developers.
> 
> This seems to be the generic error message for "something went wrong in
> sphinx multiprocess":
> - https://github.com/sphinx-doc/sphinx/issues/11449
> - https://github.com/sphinx-doc/sphinx/issues/14458
> - https://github.com/sphinx-doc/sphinx/issues/8973
> 
> Solve the issue by simply going back to sequential builds. We didn't
> notice a huge speedup anyway.

> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
> ---
>   docs/meson.build | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Michael Tokarev <mjt@tls.msk.ru>

Thanks,

/mjt
Re: [PATCH] docs: fix sphinx build failure
Posted by Stefan Hajnoczi 3 days, 17 hours ago 
On Mon, Jul 20, 2026 at 6:28 PM Pierrick Bouvier
<pierrick.bouvier@oss.qualcomm.com> wrote:
>
> We recently started to have those failures appearing when building
> documentation. It's hard to identify if it comes from a python, sphinx
> or sphinx extension, but it blocks us.
>
> Exception occurred:
>   File "/usr/lib/python3.13/multiprocessing/connection.py", line 399, in _recv
>     raise EOFError
> EOFError
> The full traceback has been saved in /tmp/sphinx-*.log, if you want to report the issue to the developers.
>
> This seems to be the generic error message for "something went wrong in
> sphinx multiprocess":
> - https://github.com/sphinx-doc/sphinx/issues/11449
> - https://github.com/sphinx-doc/sphinx/issues/14458
> - https://github.com/sphinx-doc/sphinx/issues/8973
>
> Solve the issue by simply going back to sequential builds. We didn't
> notice a huge speedup anyway.
>
> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
> ---
>  docs/meson.build | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Michael's reply suggests there might be other factors involved in
these errors too, but there is no harm in applying this patch:

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Re: [PATCH] docs: fix sphinx build failure
Posted by Michael Tokarev 4 days, 2 hours ago 
On 21.07.2026 01:27, Pierrick Bouvier wrote:
> We recently started to have those failures appearing when building
> documentation. It's hard to identify if it comes from a python, sphinx
> or sphinx extension, but it blocks us.
> 
> Exception occurred:
>    File "/usr/lib/python3.13/multiprocessing/connection.py", line 399, in _recv
>      raise EOFError
> EOFError
> The full traceback has been saved in /tmp/sphinx-*.log, if you want to report the issue to the developers.
> 
> This seems to be the generic error message for "something went wrong in
> sphinx multiprocess":
> - https://github.com/sphinx-doc/sphinx/issues/11449
> - https://github.com/sphinx-doc/sphinx/issues/14458
> - https://github.com/sphinx-doc/sphinx/issues/8973

FWIW, this time, it looks like it is a genuine bug in debian update of
python3.  I was able to reproduce the issue without -j option too, after
about 300 retries (did build in a loop), and the python backtrace (it
segfaulted) shows pattern similar to what was reported on debian.
I haven't reproduced it after installing the fixed packages, but with
so many attempts to failure, about 500 successful runs in a row is
not conclusive still.

> Solve the issue by simply going back to sequential builds. We didn't
> notice a huge speedup anyway.

The thing is: it looks like actually, at least the version of sphinx
I have on debian stable - sphinx ignores -j option always using single
core no matter which -j arg it is given.  I weren't able to run it in
true parallel mode.  Maybe it spawns single "parallel" thread still,
exploring the problematic code paths still, and without -j it wont -
I dunno.

So, I guess, with this in mind, it should definitely be okay to have
this change.

Thanks,

/mjt

> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
> ---
>   docs/meson.build | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/meson.build b/docs/meson.build
> index a8d893681ec..4d8cc545fcc 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -4,7 +4,7 @@ sphinx_build = find_program(fs.parent(python.full_path()) / 'sphinx-build',
>   # Check if tools are available to build documentation.
>   build_docs = false
>   if sphinx_build.found()
> -  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q', '-j', 'auto']
> +  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q']
>     # If we're making warnings fatal, apply this to Sphinx runs as well
>     if get_option('werror')
>       SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
Re: [PATCH] docs: fix sphinx build failure
Posted by Pierrick Bouvier 3 days, 18 hours ago 
On 7/21/2026 12:51 AM, Michael Tokarev wrote:
> On 21.07.2026 01:27, Pierrick Bouvier wrote:
>> We recently started to have those failures appearing when building
>> documentation. It's hard to identify if it comes from a python, sphinx
>> or sphinx extension, but it blocks us.
>>
>> Exception occurred:
>>    File "/usr/lib/python3.13/multiprocessing/connection.py", line 399,
>> in _recv
>>      raise EOFError
>> EOFError
>> The full traceback has been saved in /tmp/sphinx-*.log, if you want to
>> report the issue to the developers.
>>
>> This seems to be the generic error message for "something went wrong in
>> sphinx multiprocess":
>> - https://github.com/sphinx-doc/sphinx/issues/11449
>> - https://github.com/sphinx-doc/sphinx/issues/14458
>> - https://github.com/sphinx-doc/sphinx/issues/8973
> 
> FWIW, this time, it looks like it is a genuine bug in debian update of
> python3.  I was able to reproduce the issue without -j option too, after
> about 300 retries (did build in a loop), and the python backtrace (it
> segfaulted) shows pattern similar to what was reported on debian.
> I haven't reproduced it after installing the fixed packages, but with
> so many attempts to failure, about 500 successful runs in a row is
> not conclusive still.
> 
>> Solve the issue by simply going back to sequential builds. We didn't
>> notice a huge speedup anyway.
> 
> The thing is: it looks like actually, at least the version of sphinx
> I have on debian stable - sphinx ignores -j option always using single
> core no matter which -j arg it is given.  I weren't able to run it in
> true parallel mode.  Maybe it spawns single "parallel" thread still,
> exploring the problematic code paths still, and without -j it wont -
> I dunno.
> 
> So, I guess, with this in mind, it should definitely be okay to have
> this change.
>

Good to know if might be fixed in the future with a python update. We
can re-include it at this time.
I can send a PR current fix once the patch has received a reviewed-by.

Regards,
Pierrick

> Thanks,
> 
> /mjt
> 
>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
>> ---
>>   docs/meson.build | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/docs/meson.build b/docs/meson.build
>> index a8d893681ec..4d8cc545fcc 100644
>> --- a/docs/meson.build
>> +++ b/docs/meson.build
>> @@ -4,7 +4,7 @@ sphinx_build =
>> find_program(fs.parent(python.full_path()) / 'sphinx-build',
>>   # Check if tools are available to build documentation.
>>   build_docs = false
>>   if sphinx_build.found()
>> -  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-
>> q', '-j', 'auto']
>> +  SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q']
>>     # If we're making warnings fatal, apply this to Sphinx runs as well
>>     if get_option('werror')
>>       SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
>

Patchew 2.1-devel-ea86937

© 2016 - 2026 Red Hat, Inc.