[PATCH v6 14/21] tools/docs,scripts: sphinx-*: prevent sphinx-build crashes
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2025-09-16 10:23:37
Also in:
lkml
Subsystem:
documentation, documentation scripts, the rest · Maintainers:
Jonathan Corbet, Mauro Carvalho Chehab, Linus Torvalds
On a properly set system, LANG and LC_ALL is always defined. However, some distros like Debian, Gentoo and their variants start with those undefioned. When Sphinx tries to set a locale with: locale.setlocale(locale.LC_ALL, '') It raises an exception, making Sphinx fail. This is more likely to happen with test containers. Add a logic to detect and workaround such issue by setting locale to C. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- tools/docs/sphinx-build-wrapper | 11 +++++++++++ tools/docs/sphinx-pre-install | 14 +++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-)
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 413f51575de8..629abb99b9f3 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper@@ -45,6 +45,7 @@ the newer version. """ import argparse +import locale import os import shlex import shutil
@@ -457,6 +458,16 @@ class SphinxBuilder: if not sphinxdirs: sphinxdirs = os.environ.get("SPHINXDIRS", ".") + # + # The sphinx-build tool has a bug: internally, it tries to set + # locale with locale.setlocale(locale.LC_ALL, ''). This causes a + # crash if language is not set. Detect and fix it. + # + try: + locale.setlocale(locale.LC_ALL, '') + except locale.Error: + self.env["LC_ALL"] = "C" + # # sphinxdirs can be a list or a whitespace-separated string #
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index d6d673b7945c..663d4e2a3f57 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install@@ -26,6 +26,7 @@ system pacage install is recommended. """ import argparse +import locale import os import re import subprocess
@@ -422,8 +423,19 @@ class MissingCheckers(AncillaryMethods): """ Gets sphinx-build version. """ + env = os.environ.copy() + + # The sphinx-build tool has a bug: internally, it tries to set + # locale with locale.setlocale(locale.LC_ALL, ''). This causes a + # crash if language is not set. Detect and fix it. try: - result = self.run([cmd, "--version"], + locale.setlocale(locale.LC_ALL, '') + except Exception: + env["LC_ALL"] = "C" + env["LANG"] = "C" + + try: + result = self.run([cmd, "--version"], env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, check=True)
--
2.51.0