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

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

[Zhixu Liu]

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

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

[Jonathan Corbet]

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

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

[Zhixu Liu]

> 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

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

[Zhixu Liu]

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