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

PATCH New Jonathan Corbet 1 participant 1 message Sep 9, 2025

Subsystems (2)

Documentation Documentation scripts

lore

Share & tools

lore

Jonathan Corbet

author maintainer

2025-09-09 19:35 UTC #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.

Reported-by Zhixu Liu <[email protected]>

Signed-off-by Jonathan Corbet <[email protected]>

---
 Documentation/sphinx/kernel_feat.py         | 4 +++-
 Documentation/sphinx/kernel_include.py      | 6 ++++--
 Documentation/sphinx/maintainers_include.py | 4 +++-
 3 files changed, 10 insertions(+), 4 deletions(-)

Documentation/sphinx/kernel_feat.py +3 -1

index e3a51867f27b..aaac76892ceb 100644
@@ -40,9 +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
 from sphinx.util.docutils import switch_source_input
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 __version__  = '1.0'
 
 def setup(app):

Documentation/sphinx/kernel_include.py +4 -2

index 2c4bb8215b4c..f94412cd17c9 100755
@@ -89,7 +89,6 @@ import sys
 
 from docutils import io, nodes, statemachine
 from docutils.statemachine import ViewList
-from docutils.utils.error_reporting import SafeString, ErrorString
 from docutils.parsers.rst import Directive, directives
 from docutils.parsers.rst.directives.body import CodeBlock, NumberLines

@@ -106,6 +105,9 @@ logger = logging.getLogger(__name__)
 RE_DOMAIN_REF = re.compile(r'\\ :(ref|c:type|c:func):`([^<`]+)(?:<([^>]+)>)?`\\')
 RE_SIMPLE_REF = re.compile(r'`([^`]+)`')
 
+def ErrorString(exc):  # Shamelessly stolen from docutils
+    return f'{exc.__class__.__name}: {exc}'
+
 
 # ==============================================================================
 class KernelInclude(Directive):

@@ -156,7 +158,7 @@ class KernelInclude(Directive):
             except UnicodeEncodeError:
                 raise self.severe('Problems with directive path:\n'
                                 'Cannot encode input file path "%s" '
-                                '(wrong locale?).' % SafeString(path))
+                                '(wrong locale?).' % path)
             except IOError as error:
                 raise self.severe('Problems with directive path:\n%s.' % ErrorString(error))

Documentation/sphinx/maintainers_include.py +3 -1

index d31cff867436..519ad18685b2 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):

Signature · 1 line

2.51.0