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

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

[marcandre.lureau]

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
 
-- 
2.34.1.8.g35151cf07204

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

[Thomas Huth]

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

  Thomas

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

[Marc-André Lureau]

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)

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

thanks

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

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

[Alex Bennée]

marcandre.lureau@redhat.com writes:

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

Queued to testing/next (as I need it for Thomas's API updates), thanks.


-- 
Alex Bennée