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

[John Snow <jsnow@redhat.com>]

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