* [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 @ 2025-09-02 14:51 Zhixu Liu 2025-09-02 15:18 ` Jonathan Corbet 0 siblings, 1 reply; 5+ messages in thread From: Zhixu Liu @ 2025-09-02 14:51 UTC (permalink / raw) To: Jonathan Corbet; +Cc: linux-doc 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 __version__ = '1.0' diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 1e566e87ebcdd..6c3cfcb904884 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -35,7 +35,12 @@ import os.path from docutils import io, nodes, statemachine -from docutils.utils.error_reporting import SafeString, ErrorString +try: + from docutils.utils.error_reporting import SafeString, ErrorString +except ImportError: + # docutils >= 0.22 + SafeString = str + from docutils.io import error_string as ErrorString from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index d31cff8674367..efd866ff066b7 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -22,7 +22,11 @@ import re import os.path from docutils import statemachine -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 docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include -- 2.49.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 2025-09-02 14:51 [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 Zhixu Liu @ 2025-09-02 15:18 ` Jonathan Corbet 2025-09-02 15:56 ` Zhixu Liu 2025-09-06 14:38 ` [PATCH v2] " Zhixu Liu 0 siblings, 2 replies; 5+ messages in thread From: Jonathan Corbet @ 2025-09-02 15:18 UTC (permalink / raw) To: Zhixu Liu; +Cc: linux-doc 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 2025-09-02 15:18 ` Jonathan Corbet @ 2025-09-02 15:56 ` Zhixu Liu 2025-09-04 3:42 ` [PATCH v3] " Zhixu Liu 2025-09-06 14:38 ` [PATCH v2] " Zhixu Liu 1 sibling, 1 reply; 5+ messages in thread From: Zhixu Liu @ 2025-09-02 15:56 UTC (permalink / raw) To: Jonathan Corbet; +Cc: linux-doc > 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? sphinx.errors.ExtensionError is reported by sphinx, following is the full traceback (ModuleNotFoundError is a Built-in subclass of ImportError, which is introduced since python 3.6): Traceback (most recent call last): File "/usr/lib/python3.12/site-packages/sphinx/registry.py", line 541, in load_extension mod = import_module(extname) ^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module return _bootstrap._gcd_import(name[level:], package, level) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import File "<frozen importlib._bootstrap>", line 1360, in _find_and_load File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 935, in _load_unlocked File "<frozen importlib._bootstrap_external>", line 999, in exec_module File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed File "/var/tmp/portage/sys-kernel/linux-docs-6.16.4/work/linux-6.16.4/Documentation/sphinx/kernel_include.py", line 37, in <module> from docutils.utils.error_reporting import SafeString, ErrorString ModuleNotFoundError: No module named 'docutils.utils.error_reporting' The above exception was the direct cause of the following exception: Traceback (most recent call last): File "/usr/lib/python3.12/site-packages/sphinx/cmd/build.py", line 414, in build_main app = Sphinx( ^^^^^^^ File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 291, in __init__ self.setup_extension(extension) File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 489, in setup_extension self.registry.load_extension(self, extname) 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') > I would still rather just look at the docutils version in any case, > rather than trying to interpret exceptions. > > Thanks, > > jon -- Z. Liu ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v3] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 2025-09-02 15:56 ` Zhixu Liu @ 2025-09-04 3:42 ` Zhixu Liu 0 siblings, 0 replies; 5+ messages in thread From: Zhixu Liu @ 2025-09-04 3:42 UTC (permalink / raw) To: Jonathan Corbet; +Cc: linux-doc docutils.utils.error_reporting was removed in docutils v0.22, causing sphinx extensions (e.g. kernel_include) to fail with: Traceback (most recent call last): File "/usr/lib/python3.12/site-packages/sphinx/registry.py", line 541, in load_extension mod = import_module(extname) ^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3.12/importlib/__init__.py", line 90, in import_module return _bootstrap._gcd_import(name[level:], package, level) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import File "<frozen importlib._bootstrap>", line 1360, in _find_and_load File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked File "<frozen importlib._bootstrap>", line 935, in _load_unlocked File "<frozen importlib._bootstrap_external>", line 999, in exec_module File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed File "/var/tmp/portage/sys-kernel/linux-docs-6.16.4/work/linux-6.16.4/Documentation/sphinx/kernel_include.py", line 37, in <module> from docutils.utils.error_reporting import SafeString, ErrorString ModuleNotFoundError: No module named 'docutils.utils.error_reporting' The above exception was the direct cause of the following exception: Traceback (most recent call last): File "/usr/lib/python3.12/site-packages/sphinx/cmd/build.py", line 414, in build_main app = Sphinx( ^^^^^^^ File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 291, in __init__ self.setup_extension(extension) File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 489, in setup_extension self.registry.load_extension(self, extname) 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() ModuleNotFoundError is a subclass of ImportError, added in python 3.6. 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 __version__ = '1.0' diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index 1e566e87ebcdd..6c3cfcb904884 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -35,7 +35,12 @@ import os.path from docutils import io, nodes, statemachine -from docutils.utils.error_reporting import SafeString, ErrorString +try: + from docutils.utils.error_reporting import SafeString, ErrorString +except ImportError: + # docutils >= 0.22 + SafeString = str + from docutils.io import error_string as ErrorString from docutils.parsers.rst import directives from docutils.parsers.rst.directives.body import CodeBlock, NumberLines from docutils.parsers.rst.directives.misc import Include diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index d31cff8674367..efd866ff066b7 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -22,7 +22,11 @@ import re import os.path from docutils import statemachine -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 docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include -- 2.49.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 2025-09-02 15:18 ` Jonathan Corbet 2025-09-02 15:56 ` Zhixu Liu @ 2025-09-06 14:38 ` Zhixu Liu 1 sibling, 0 replies; 5+ messages in thread From: Zhixu Liu @ 2025-09-06 14:38 UTC (permalink / raw) To: Jonathan Corbet; +Cc: linux-doc 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2025-09-06 14:39 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-09-02 14:51 [PATCH v2] docs: sphinx: handle removal of utils.error_reporting in docutils 0.22 Zhixu Liu 2025-09-02 15:18 ` Jonathan Corbet 2025-09-02 15:56 ` Zhixu Liu 2025-09-04 3:42 ` [PATCH v3] " Zhixu Liu 2025-09-06 14:38 ` [PATCH v2] " Zhixu Liu
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).