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

[Laszlo Ersek <lersek@redhat.com>]

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