Skip to contentSkip to conversation

docs: fix trace docs build with sphinx 3.1.1

PATCH Applied Daniel P. Berrangé 8 participants 11 messages Jul 14, 2020 – Sep 8, 2020

lore
Share & tools
lore
#0 lore raw

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
index 7e09773a9c..e79b0b43fc 100644
@@ -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
#1 lore raw
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]

#2 lore raw
In reply to Daniel P. Berrangé
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]

#3 lore raw
In reply to Daniel P. Berrangé
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.

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."
#4 lore raw
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

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

#5 lore raw
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

#6 lore raw
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 ...)

#7 lore raw
In reply to Daniel P. Berrangé
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 4 lines
---
 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

#8 lore raw
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
---
 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 :|
#9 lore raw
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.

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

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

#10 lore raw
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
---
 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.

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