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