Skip to contentSkip to conversation

docs: kdoc: handle the obsolescensce of docutils.ErrorString()

PATCH In review J. Neuschäfer 2 participants 2 messages Jan 1 – Jan 2

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: kdoc: handle the obsolescensce of docutils.ErrorString()

The ErrorString() and SafeString() docutils functions were helpers meant to ease the handling of encodings during the Python 3 transition. There is no real need for them after Python 3.6, and docutils 0.22 removes them, breaking the docs build

Handle this by just injecting our own one-liner version of ErrorString(), and removing the sole SafeString() call entirely.

Upstream: https://git.kernel.org/linus/00d95fcc4dee66dfb6980de6f2973b32f973a1eb

[j.ne: Adapted from Linux to U-Boot]
---
 doc/sphinx/kernel_abi.py          | 4 +++-
 doc/sphinx/kernel_feat.py         | 4 +++-
 doc/sphinx/kernel_include.py      | 6 ++++--
 doc/sphinx/maintainers_include.py | 4 +++-
 4 files changed, 13 insertions(+), 5 deletions(-)
doc/sphinx/kernel_abi.py +3 -1
index 32c50e496b5..930e9273b16 100644
@@ -44,7 +44,9 @@ from os import path
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
 #
 # AutodocReporter is only good up to Sphinx 1.7
doc/sphinx/kernel_feat.py +3 -1
index 2fee04f1ded..cca48f6f1a4 100644
@@ -41,7 +41,9 @@ from os import path
 from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
 #
 # AutodocReporter is only good up to Sphinx 1.7
doc/sphinx/kernel_include.py +4 -2
index f523aa68a36..6522de9dd69 100755
@@ -34,11 +34,13 @@ u"""
 import os.path
 
 from docutils import io, nodes, statemachine
-from docutils.utils.error_reporting import SafeString, ErrorString
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
 from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 __version__  = '1.0'
 
 # ==============================================================================
@@ -109,7 +111,7 @@ class KernelInclude(Include):
             raise self.severe('Problems with "%s" directive path:\n'
                               'Cannot encode input file path "%s" '
                               '(wrong locale?).' %
-                              (self.name, SafeString(path)))
+                              (self.name, path))
         except IOError as error:
             raise self.severe('Problems with "%s" directive path:\n%s.' %
                       (self.name, ErrorString(error)))
doc/sphinx/maintainers_include.py +3 -1
index 13557d3d3c2..ab79a74dc0c 100755
@@ -22,10 +22,12 @@ import re
 import os.path
 
 from docutils import statemachine
-from docutils.utils.error_reporting import ErrorString
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 __version__  = '1.0'
 
 def setup(app):

---
base-commit: bb28daf51301546fc2b6882e51f39f5d12952375
change-id: 20260101-docutils-5899af0ac74b

Best regards,

Signature · 1 line
J. Neuschäfer <[email protected]>
Reviewed-by on v1 1/1
#1 lore raw
Quoted 7 lines · On 1/1/26 15:31, J. Neuschäfer via B4 Relay wrote:

From: "J. Neuschäfer" <[email protected]>

The ErrorString() and SafeString() docutils functions were helpers meant to ease the handling of encodings during the Python 3 transition. There is no real need for them after Python 3.6, and docutils 0.22 removes them, breaking the docs build

Quoted 8 lines

Handle this by just injecting our own one-liner version of ErrorString(), and removing the sole SafeString() call entirely.

Upstream: https://git.kernel.org/linus/00d95fcc4dee66dfb6980de6f2973b32f973a1eb

[j.ne: Adapted from Linux to U-Boot]

path = nodes.reprunicode(path)
in doc/sphinx/kernel_include.py is also not supported anymore.

Quoted 89 lines
---
  doc/sphinx/kernel_abi.py          | 4 +++-
  doc/sphinx/kernel_feat.py         | 4 +++-
  doc/sphinx/kernel_include.py      | 6 ++++--
  doc/sphinx/maintainers_include.py | 4 +++-
  4 files changed, 13 insertions(+), 5 deletions(-)
doc/sphinx/kernel_abi.py +3 -1
index 32c50e496b5..930e9273b16 100644
@@ -44,7 +44,9 @@ from os import path
  from docutils import nodes, statemachine
  from docutils.statemachine import ViewList
  from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
  #
  # AutodocReporter is only good up to Sphinx 1.7
doc/sphinx/kernel_feat.py +3 -1
index 2fee04f1ded..cca48f6f1a4 100644
@@ -41,7 +41,9 @@ from os import path
  from docutils import nodes, statemachine
  from docutils.statemachine import ViewList
  from docutils.parsers.rst import directives, Directive
-from docutils.utils.error_reporting import ErrorString
+
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
 
  #
  # AutodocReporter is only good up to Sphinx 1.7
doc/sphinx/kernel_include.py +4 -2
index f523aa68a36..6522de9dd69 100755
@@ -34,11 +34,13 @@ u"""
  import os.path
 
  from docutils import io, nodes, statemachine
-from docutils.utils.error_reporting import SafeString, ErrorString
  from docutils.parsers.rst import directives
  from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
  from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
  __version__  = '1.0'
 
  # ==============================================================================
@@ -109,7 +111,7 @@ class KernelInclude(Include):
              raise self.severe('Problems with "%s" directive path:\n'
                                'Cannot encode input file path "%s" '
                                '(wrong locale?).' %
-                              (self.name, SafeString(path)))
+                              (self.name, path))
          except IOError as error:
              raise self.severe('Problems with "%s" directive path:\n%s.' %
                        (self.name, ErrorString(error)))
doc/sphinx/maintainers_include.py +3 -2
index 13557d3d3c2..ab79a74dc0c 100755
@@ -22,10 +22,12 @@ import re
  import os.path
 
  from docutils import statemachine
-from docutils.utils.error_reporting import ErrorString
  from docutils.parsers.rst import Directive
  from docutils.parsers.rst.directives.misc import Include
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
  __version__  = '1.0'
 
  def setup(app):
 
---

base-commit: bb28daf51301546fc2b6882e51f39f5d12952375
change-id: 20260101-docutils-5899af0ac74b

Best regards,