Re: [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22

[Zhixu Liu <zhixu.liu@gmail.com>]

Hi Jonathan,

How about the v3 patch? I still think try/except is more robust,
but I can switch to version comparison if you prefer, e.g.:

if docutils.__version_info__ >= (0, 22):
    ...
else:
    ...

My preference for try/except:

1. Reflects the actual runtime environment, while version checks can
be broken by backported patches.
2. Avoids parsing non-standard version strings (e.g. 0.21a1,
0.21.dev0); try/except is simpler and has no extra dependencies.
(__version_info__ mitigates this somewhat.)
3. More Pythonic and straightforward.

I’m fine with either approach—please let me know which you’d like me to go with.

On Tue, Sep 2, 2025 at 11:18 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Zhixu Liu <zhixu.liu@gmail.com> writes:
>
> > docutils.utils.error_reporting was removed in docutils v0.22, causing sphinx
> > extensions (e.g. kernel_include) to fail with:
> >
> >>   File "/usr/lib/python3.12/site-packages/sphinx/registry.py", line 544, in load_extension
> >>     raise ExtensionError(
> >> sphinx.errors.ExtensionError: Could not import extension kernel_include (exception: No module named 'docutils.utils.error_reporting')
> >
> > Add compatibility handling with try/except (more robust than checking
> > version numbers):
> > - SafeString  -> str
> > - ErrorString -> docutils.io.error_string()
> >
> > Signed-off-by: Z. Liu <zhixu.liu@gmail.com>
> > ---
> >  Documentation/sphinx/kernel_feat.py         | 6 +++++-
> >  Documentation/sphinx/kernel_include.py      | 7 ++++++-
> >  Documentation/sphinx/maintainers_include.py | 6 +++++-
> >  3 files changed, 16 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/sphinx/kernel_feat.py
> > b/Documentation/sphinx/kernel_feat.py
> > index e3a51867f27bd..d077645254cd4 100644
> > --- a/Documentation/sphinx/kernel_feat.py
> > +++ b/Documentation/sphinx/kernel_feat.py
> > @@ -40,7 +40,11 @@ import sys
> >  from docutils import nodes, statemachine
> >  from docutils.statemachine import ViewList
> >  from docutils.parsers.rst import directives, Directive
> > -from docutils.utils.error_reporting import ErrorString
> > +try:
> > +    from docutils.utils.error_reporting import ErrorString
> > +except ImportError:
> > +    # docutils >= 0.22
> > +    from docutils.io import error_string as ErrorString
> >  from sphinx.util.docutils import switch_source_input
>
> This is a step in the right direction ... but the exception you report
> in the changelog is sphinx.errors.ExtensionError; why a different
> exception here?
>
> I would still rather just look at the docutils version in any case,
> rather than trying to interpret exceptions.
>
> Thanks,
>
> jon



-- 
Z. Liu