Re: [PATCH] docs/sphinx: fix compatibility with sphinx < 1.8

[Thomas Huth]

On 04/01/2022 09.15, Marc-André Lureau wrote:
> Hi Thomas
>
> On Tue, Jan 4, 2022 at 12:11 PM Thomas Huth <thuth@redhat.com> wrote:
> > On 04/01/2022 08.46, marcandre.lureau@redhat.com wrote:
> > > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> > >
> > > SphinxDirective was added with sphinx 1.8 (2018-09-13).
> > >
> > > Reported-by: Thomas Huth <thuth@redhat.com>
> > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > > ---
> > >    docs/sphinx/fakedbusdoc.py | 4 ++--
> > >    1 file changed, 2 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/docs/sphinx/fakedbusdoc.py b/docs/sphinx/fakedbusdoc.py
> > > index a680b257547f..d2c507904654 100644
> > > --- a/docs/sphinx/fakedbusdoc.py
> > > +++ b/docs/sphinx/fakedbusdoc.py
> > > @@ -7,12 +7,12 @@
> > >    # Author: Marc-André Lureau <marcandre.lureau@redhat.com>
> > >    """dbus-doc is a Sphinx extension that provides documentation from D-Bus 
> > > XML."""
> > >
> > > +from docutils.parsers.rst import Directive
> > >    from sphinx.application import Sphinx
> > > -from sphinx.util.docutils import SphinxDirective
> > >    from typing import Any, Dict
> > >
> > >
> > > -class FakeDBusDocDirective(SphinxDirective):
> > > +class FakeDBusDocDirective(Directive):
> > >        has_content = True
> > >        required_arguments = 1
> >
> > Thanks, that fixes my issue, indeed!
> >
> > Tested-by: Thomas Huth <thuth@redhat.com>
> >
> > I wonder whether we could turn such sphinx warnings during the configure
> > phase into a hard failure so that such bugs would fail in the CI instead of
> > getting merge without notice...?
>
> I don't think there is a way to set the max sphinx version (an
> argument such as --max-version=1.7.9)

Yes, I didn't expect that... I was rather wondering whether warnings could 
be turned into errors - and there seems to be "-W" option indeed ... and 
looking at docs/meson.build, we even use it if configuration has been done 
with --enable-werror !

> The only way I can think of is to cover building with that version in
> the CI, as long as it is supported.

I thought that it would have slipped through the CI since the warning was 
ignored - but it rather seems like it slipped through since the CentOS job 
is not building the docs at all! See:

 https://gitlab.com/qemu-project/qemu/-/jobs/1937664125#L260

I'll send a patch to use --enable-docs there, too:

 https://gitlab.com/thuth/qemu/-/jobs/1938762318#L4071

 Thomas