docs: fix trace docs build with sphinx 3.1.1
PATCH 1/1 docs: fix trace docs build with sphinx 3.1.1
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"
This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
--- docs/qemu-option-trace.rst.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
docs/qemu-option-trace.rst.inc +3 -3
@@ -1,7 +1,7 @@ Specify tracing options. -.. option:: [enable=]PATTERN +.. option:: -trace [enable=]PATTERN Immediately enable events matching *PATTERN* (either event name or a globbing pattern). This option is only
@@ -11,7 +11,7 @@ Specify tracing options. Use :option:`-trace help` to print a list of names of trace points. -.. option:: events=FILE +.. option:: -trace events=FILE Immediately enable events listed in *FILE*. The file must contain one event name (as listed in the ``trace-events-all``
@@ -19,7 +19,7 @@ Specify tracing options. available if QEMU has been compiled with the ``simple``, ``log`` or ``ftrace`` tracing backend. -.. option:: file=FILE +.. option:: -trace file=FILE Log output traces to *FILE*. This option is only available if QEMU has been compiled with
Signature · 1 line
2.24.1
Patchew URL: https://patchew.org/QEMU/[email protected]/
Patchew URL: https://patchew.org/QEMU/[email protected]/
Hi,
This series failed the docker-mingw@fedora build test. Please find the testing commands and their output below. If you have Docker installed, you can probably reproduce it locally.
=== TEST SCRIPT BEGIN ===
#! /bin/bash
export ARCH=x86_64
make docker-image-fedora V=1 NETWORK=1
time make docker-test-mingw@fedora J=14 NETWORK=1
=== TEST SCRIPT END ===
CC authz/trace.o
CC block/trace.o
Warning, treated as error:
../src/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-qemu-img-trace".
CC io/trace.o CC nbd/trace.o CC scsi/trace.o CC audio/trace.o
Warning, treated as error:
../src/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-qemu-img-trace".
CC chardev/trace.o
CC hw/9pfs/trace.o
---
CC hw/hyperv/trace.o CC hw/i2c/trace.o CC hw/i386/trace.o
make: *** [Makefile:1102: docs/tools/index.html] Error 2
make: *** Waiting for unfinished jobs....
make: *** [Makefile:1112: .docs_tools_qemu-img.1_docs_tools_qemu-nbd.8_docs_tools_qemu-trace-stap.1_docs_tools_virtiofsd.1_docs_tools_virtfs-proxy-helper.1.sentinel.] Error 2
make: *** Deleting file '.docs_tools_qemu-img.1_docs_tools_qemu-nbd.8_docs_tools_qemu-trace-stap.1_docs_tools_virtiofsd.1_docs_tools_virtfs-proxy-helper.1.sentinel.'
Warning, treated as error:
../src/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-trace".
make: *** [Makefile:1110: .docs_system_qemu.1_docs_system_qemu-block-drivers.7_docs_system_qemu-cpu-models.7.sentinel.] Error 2
make: *** Deleting file '.docs_system_qemu.1_docs_system_qemu-block-drivers.7_docs_system_qemu-cpu-models.7.sentinel.'
Warning, treated as error:
../src/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-trace".
make: *** [Makefile:1099: docs/system/index.html] Error 2
Traceback (most recent call last):
File "./tests/docker/docker.py", line 702, in <module>
sys.exit(main())
---
raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['sudo', '-n', 'docker', 'run', '--label', 'com.qemu.instance.uuid=74976b19cfaa4c07a430b88e4a00cdec', '-u', '1003', '--security-opt', 'seccomp=unconfined', '--rm', '-e', 'TARGET_LIST=', '-e', 'EXTRA_CONFIGURE_OPTS=', '-e', 'V=', '-e', 'J=14', '-e', 'DEBUG=', '-e', 'SHOW_ENV=', '-e', 'CCACHE_DIR=/var/tmp/ccache', '-v', '/home/patchew2/.cache/qemu-docker-ccache:/var/tmp/ccache:z', '-v', '/var/tmp/patchew-tester-tmp-um58z9k1/src/docker-src.2020-07-14-12.53.28.7929:/var/tmp/qemu:z,ro', 'qemu/fedora', '/var/tmp/qemu/run', 'test-mingw']' returned non-zero exit status 2. filter=--filter=label=com.qemu.instance.uuid=74976b19cfaa4c07a430b88e4a00cdec
make[1]: *** [docker-run] Error 1
make[1]: Leaving directory `/var/tmp/patchew-tester-tmp-um58z9k1/src'
make: *** [docker-run-test-mingw@fedora] Error 2
real 3m0.912s
user 0m8.019s
The full log is available at
http://patchew.org/logs/[email protected]/testing.docker-mingw@fedora/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to [email protected]
Patchew URL: https://patchew.org/QEMU/[email protected]/
Patchew URL: https://patchew.org/QEMU/[email protected]/
Hi,
This series failed the docker-quick@centos7 build test. Please find the testing commands and their output below. If you have Docker installed, you can probably reproduce it locally.
=== TEST SCRIPT BEGIN ===
#!/bin/bash
make docker-image-centos7 V=1 NETWORK=1
time make docker-test-quick@centos7 SHOW_ENV=1 J=14 NETWORK=1 === TEST SCRIPT END ===
TEST iotest-qcow2: 024
TEST check-unit: tests/test-char
**
ERROR:/tmp/qemu-test/src/tests/test-char.c:1204:char_serial_test: 'chr' should not be NULL
ERROR test-char - Bail out! ERROR:/tmp/qemu-test/src/tests/test-char.c:1204:char_serial_test: 'chr' should not be NULL
make: *** [check-unit] Error 1
make: *** Waiting for unfinished jobs....
qemu-system-aarch64: -accel kvm: invalid accelerator kvm
qemu-system-aarch64: falling back to tcg
---
raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['sudo', '-n', 'docker', 'run', '--label', 'com.qemu.instance.uuid=ee90d27b35364342aac88818477b8e5c', '-u', '1001', '--security-opt', 'seccomp=unconfined', '--rm', '-e', 'TARGET_LIST=', '-e', 'EXTRA_CONFIGURE_OPTS=', '-e', 'V=', '-e', 'J=14', '-e', 'DEBUG=', '-e', 'SHOW_ENV=1', '-e', 'CCACHE_DIR=/var/tmp/ccache', '-v', '/home/patchew/.cache/qemu-docker-ccache:/var/tmp/ccache:z', '-v', '/var/tmp/patchew-tester-tmp-9f8ignz7/src/docker-src.2020-07-14-12.48.51.16596:/var/tmp/qemu:z,ro', 'qemu/centos7', '/var/tmp/qemu/run', 'test-quick']' returned non-zero exit status 2. filter=--filter=label=com.qemu.instance.uuid=ee90d27b35364342aac88818477b8e5c
make[1]: *** [docker-run] Error 1
make[1]: Leaving directory `/var/tmp/patchew-tester-tmp-9f8ignz7/src'
make: *** [docker-run-test-quick@centos7] Error 2
real 15m38.865s
user 0m8.774s
The full log is available at
http://patchew.org/logs/[email protected]/testing.docker-quick@centos7/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to [email protected]
Quoted 8 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"
Quoted 8 lines
This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Signed-off-by Daniel P. Berrangé <[email protected]>
Running Sphinx v1.7.6
[...]
Warning, treated as error:
../qemu-5.0.0/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-qemu-img-trace".
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1 "And now for something completely different."
Quoted 17 lines · Andreas Schwab
Quoted 15 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Quoted 9 lines
Quoted 1 line
Signed-off-by Daniel P. Berrangé <[email protected]>Running Sphinx v1.7.6
[...]
Warning, treated as error:
../qemu-5.0.0/docs/qemu-option-trace.rst.inc:21:Duplicate explicit target name: "cmdoption-qemu-img-trace".Andreas.
I ran into this before, I forget what causes it, or how I fixed it ...
Oh, it was part of the research I was doing into why we can't support Sphinx prior to 1.6; and it's documented in conf.py:
# Sphinx 1.5 and earlier can't build our docs because they are too
# picky about the syntax of the argument to the option:: directive
# (see Sphinx bugs #646, #3366).
needs_sphinx = '1.6'
... Should we say goodbye to Sphinx 1.7.x, or is there a workaround that keeps support from 1.6.1 through to 3.1.1?
--js
Quoted 2 lines · John Snow
... Should we say goodbye to Sphinx 1.7.x, or is there a workaround that keeps support from 1.6.1 through to 3.1.1?
I think we need to keep 1.7.x because it's the Sphinx shipped by some LTS distros we support, don't we?
I do feel we probably need to defend our Sphinx-version-support more actively by having oldest-supported and bleeding-edge both tested in the CI setup...
thanks
-- PMM
Quoted 7 lines · Peter Maydell
Quoted 2 lines · John Snow
... Should we say goodbye to Sphinx 1.7.x, or is there a workaround that keeps support from 1.6.1 through to 3.1.1?
I think we need to keep 1.7.x because it's the Sphinx shipped by some LTS distros we support, don't we?
Only if you feel it's important that doc building works using packages from the system repo. pip3 install --user sphinx works on all of these distros, too.
We already somewhat break our promise where Sphinx is concerned for the oldest distros on our support list.
Quoted 4 lines
I do feel we probably need to defend our Sphinx-version-support more actively by having oldest-supported and bleeding-edge both tested in the CI setup...
We could either:
A) Start using a "build venv" that uses specific sets of python packages for the build process to pin everyone's build at version 1.6.1
B) Add some sort of pytest/tox/whatever to add a test that does a sphinx doc build across multiple different versions, 1.6.1, 1.7.x, 2.0.x, etc.
(I don't think you liked the idea of a Python environment in QEMU taking responsibility of Sphinx, though ...)
Stefan Hajnoczi
AppliedQuoted 15 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Quoted 4 lines
Signed-off-by Daniel P. Berrangé <[email protected]>--- docs/qemu-option-trace.rst.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Thanks, applied to my tracing tree:
https://github.com/stefanha/qemu/commits/tracing
Stefan
Quoted 16 lines · Stefan Hajnoczi
Quoted 15 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Quoted 7 lines
Quoted 4 lines
Signed-off-by Daniel P. Berrangé <[email protected]>--- docs/qemu-option-trace.rst.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Thanks, applied to my tracing tree:
https://github.com/stefanha/qemu/commits/tracing
I'm not sure this is a good idea to queue it, based on the other part of this thread about incompatibilities with differnet sphinx versions, and the patchew failures.
I don't have a answer for how to fix this to make every versions happy.
Regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Quoted 22 lines · Daniel P. Berrangé
Quoted 21 lines · Stefan Hajnoczi
Quoted 19 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Signed-off-by Daniel P. Berrangé <[email protected]>--- docs/qemu-option-trace.rst.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Quoted 8 lines
Quoted 2 lines
Thanks, applied to my tracing tree:
https://github.com/stefanha/qemu/commits/tracingI'm not sure this is a good idea to queue it, based on the other part of this thread about incompatibilities with differnet sphinx versions, and the patchew failures.
I don't have a answer for how to fix this to make every versions happy.
Yes, thanks. I was playing around with it and considering Sphinx suppress_warnings.
Let's leave this patch for QEMU 5.1. Fedora rawhide is cutting-edge and has a smaller userbase than those using older Sphinx versions. At the moment we can keep the code as-is.
Stefan
Quoted 30 lines · Stefan Hajnoczi
Quoted 29 lines · Daniel P. Berrangé
Quoted 16 lines · Stefan Hajnoczi
Quoted 15 lines · Daniel P. Berrangé
In Fedora 33 rawhide, we now have sphinx 3.1.1, as opposed to previous 2.2.2. This new version generates a warning on the source:
docs/qemu-option-trace.rst.inc:4:Malformed option description
'[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args"This turns into an error when QEMU passes -W to sphinx-build
Strangely the previous 2.2.2 code has the exact same logic for checking the syntax, but it is not being triggered. While it is only complaining about the first option, I changed all the options to give consistency.
Quoted 7 lines
Quoted 4 lines
Signed-off-by Daniel P. Berrangé <[email protected]>--- docs/qemu-option-trace.rst.inc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Thanks, applied to my tracing tree:
https://github.com/stefanha/qemu/commits/tracingI'm not sure this is a good idea to queue it, based on the other part of this thread about incompatibilities with differnet sphinx versions, and the patchew failures.
Quoted 8 lines
Quoted 1 line
I don't have a answer for how to fix this to make every versions happy.
Yes, thanks. I was playing around with it and considering Sphinx
suppress_warnings.Let's leave this patch for QEMU 5.1. Fedora rawhide is cutting-edge and has a smaller userbase than those using older Sphinx versions. At the moment we can keep the code as-is.
I've hit this today, in a python3 venv which has Sphinx 3.2.1 installed with pip (from <https://pypi.org/project/Sphinx/>).
The latest pre-3.* python-sphinx packages in Koji seem to be 2.2.2-based; installing precisely "sphinx==2.2.2" with pip in the venv seems to have done the trick.
Thanks,
Laszlo