[PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[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é <berrange@redhat.com>
---
 docs/qemu-option-trace.rst.inc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/qemu-option-trace.rst.inc b/docs/qemu-option-trace.rst.inc
index 7e09773a9c..e79b0b43fc 100644
--- a/docs/qemu-option-trace.rst.inc
+++ b/docs/qemu-option-trace.rst.inc
@@ -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
-- 
2.24.1

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[no-reply]

Patchew URL: https://patchew.org/QEMU/20200714162659.1017432-1-berrange@redhat.com/



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/20200714162659.1017432-1-berrange@redhat.com/testing.docker-mingw@fedora/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[no-reply]

Patchew URL: https://patchew.org/QEMU/20200714162659.1017432-1-berrange@redhat.com/



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/20200714162659.1017432-1-berrange@redhat.com/testing.docker-quick@centos7/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Andreas Schwab]

On Jul 14 2020, Daniel P. Berrangé wrote:

> 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é <berrange@redhat.com>

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.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[John Snow]

On 7/26/20 4:49 PM, Andreas Schwab wrote:
> On Jul 14 2020, Daniel P. Berrangé wrote:
> 
>> 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é <berrange@redhat.com>
> 
> 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

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Peter Maydell]

On Mon, 27 Jul 2020 at 20:52, John Snow <jsnow@redhat.com> wrote:
> ... 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

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[John Snow]

On 7/27/20 4:14 PM, Peter Maydell wrote:
> On Mon, 27 Jul 2020 at 20:52, John Snow <jsnow@redhat.com> wrote:
>> ... 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.

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

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 951 bytes --]

On Tue, Jul 14, 2020 at 05:26:59PM +0100, Daniel P. Berrangé wrote:
> 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é <berrange@redhat.com>
> ---
>  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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Daniel P. Berrangé]

On Wed, Jul 29, 2020 at 11:37:19AM +0100, Stefan Hajnoczi wrote:
> On Tue, Jul 14, 2020 at 05:26:59PM +0100, Daniel P. Berrangé wrote:
> > 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é <berrange@redhat.com>
> > ---
> >  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
-- 
|: 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 :|

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1709 bytes --]

On Wed, Jul 29, 2020 at 12:34:15PM +0100, Daniel P. Berrangé wrote:
> On Wed, Jul 29, 2020 at 11:37:19AM +0100, Stefan Hajnoczi wrote:
> > On Tue, Jul 14, 2020 at 05:26:59PM +0100, Daniel P. Berrangé wrote:
> > > 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é <berrange@redhat.com>
> > > ---
> > >  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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH for 5.1] docs: fix trace docs build with sphinx 3.1.1

[Laszlo Ersek]

On 07/29/20 16:55, Stefan Hajnoczi wrote:
> On Wed, Jul 29, 2020 at 12:34:15PM +0100, Daniel P. Berrangé wrote:
>> On Wed, Jul 29, 2020 at 11:37:19AM +0100, Stefan Hajnoczi wrote:
>>> On Tue, Jul 14, 2020 at 05:26:59PM +0100, Daniel P. Berrangé wrote:
>>>> 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é <berrange@redhat.com>
>>>> ---
>>>>  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.
> 
> 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