[PATCH v3 0/6] docs: sphinx-pre-install: improve dependency checks

[PATCH v3 0/6] docs: sphinx-pre-install: improve dependency checks

[Chen Miao]

Hi all,

The Sphinx dependency checker currently does not provide useful
installation guidance on macOS and only checks whether a make executable
exists. This can leave macOS users without a clear setup path and allow an
incompatible make implementation to pass the dependency check before the
documentation build fails.

This series:

- documents the case-sensitive APFS volume needed for a kernel tree on
  macOS;
- adds macOS/Homebrew dependency handling, including command-line-only
  MacTeX support, required PDF font casks, and a PATH refresh hint;
- checks for GNU Make 4.0 or newer and honors an exported MAKE before
  preferring Homebrew gmake;
- teaches sphinx-build-wrapper to select a compatible GNU Make lazily for
  Info and Rust docs; and
- updates the zh_CN documentation in separate patches, including the APFS
  guidance in the contributor how-to.

Changes in v3:

- restore the PyYAML availability check on macOS, as the parser_yaml
  extension requires it regardless of how Sphinx is installed; and
- move GNU Make version parsing and command selection to the shared
  tools/lib/python/kdoc/gmake_detect.py module, used by both the dependency
  checker and Sphinx build wrapper.

Link: https://lore.kernel.org/linux-doc/20260810143311.57775-1-chenmiao.ku@gmail.com/

Thanks,
Chen Miao

Chen Miao (6):
  docs: kdoc: add GNU Make detection
  docs: sphinx-pre-install: add macOS Homebrew support
  docs: sphinx-pre-install: check GNU Make version
  docs: sphinx-build-wrapper: prefer gmake
  docs/zh_CN: doc-guide: document macOS Sphinx setup
  docs/zh_CN: how-to: document case-sensitive APFS setup

 Documentation/doc-guide/sphinx.rst            |  20 +++
 .../translations/zh_CN/doc-guide/sphinx.rst   |  17 ++-
 Documentation/translations/zh_CN/how-to.rst   |   8 ++
 tools/docs/sphinx-build-wrapper               |  23 +++-
 tools/docs/sphinx-pre-install                 | 120 +++++++++++++++++-
 tools/lib/python/kdoc/gmake_detect.py         |  62 +++++++++
 6 files changed, 241 insertions(+), 9 deletions(-)
 create mode 100644 tools/lib/python/kdoc/gmake_detect.py


base-commit: 8492d4e6bb7b9b1e78f2d17c4dda5272f25ec118
-- 
2.50.1 (Apple Git-155)

[PATCH v3 1/6] docs: kdoc: add GNU Make detection

[Chen Miao]

The Sphinx dependency checker and build wrapper need to select a GNU
Make executable that meets the minimum supported version. Keep the version
parsing and command selection in a common module so both tools use
identical behavior.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 tools/lib/python/kdoc/gmake_detect.py | 62 +++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 tools/lib/python/kdoc/gmake_detect.py

diff --git a/tools/lib/python/kdoc/gmake_detect.py b/tools/lib/python/kdoc/gmake_detect.py
new file mode 100644
index 000000000..5c0a28bc7
--- /dev/null
+++ b/tools/lib/python/kdoc/gmake_detect.py
@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-or-later
+# Copyright (c) 2026 Chen Miao <chenmiao.ku@gmail.com>
+
+"""Detect a supported GNU Make executable."""
+
+import re
+import shutil
+import subprocess
+import sys
+
+from kdoc.python_version import PythonVersion
+
+
+MIN_GMAKE_VERSION = PythonVersion("4.0").version
+
+
+def get_gmake_version(cmd):
+    """Return the GNU Make version for *cmd*, or ``None`` otherwise."""
+    if not cmd:
+        return None
+
+    kwargs = {}
+    if sys.version_info < (3, 7):
+        kwargs["universal_newlines"] = True
+    else:
+        kwargs["text"] = True
+
+    try:
+        result = subprocess.run(
+            [cmd, "--version"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=True,
+            **kwargs,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+
+    match = re.search(
+        r"^GNU Make\s+([0-9]+(?:\.[0-9]+)*)", result.stdout, re.MULTILINE
+    )
+    if not match:
+        return None
+
+    return PythonVersion.parse_version(match.group(1))
+
+
+def find_gmake(make=None):
+    """Return the first GNU Make 4.0+ from MAKE, gmake, or make."""
+    candidates = (
+        make,
+        shutil.which("gmake"),
+        shutil.which("make"),
+    )
+
+    for cmd in candidates:
+        version = get_gmake_version(cmd)
+        if version and version >= MIN_GMAKE_VERSION:
+            return cmd
+
+    return None
-- 
2.50.1 (Apple Git-155)

[PATCH v3 2/6] docs: sphinx-pre-install: add macOS Homebrew support

[Chen Miao]

The dependency checker currently reports an unknown distribution on macOS
and cannot provide installation hints.

Detect macOS and include its product version in the status output. Use
Homebrew for formula dependencies and install the command-line-only MacTeX
cask without sudo. Only require Homebrew when dependencies need to be
installed, install the DejaVu and Noto CJK fonts needed for PDF output, and
explain how to refresh PATH after installing MacTeX.

Keep PyYAML in the virtualenv requirements because Homebrew does not
provide a PyYAML formula. Check the module even on macOS: it is required by
the parser_yaml extension regardless of how Sphinx is installed. When it is
missing, direct users to the default virtualenv mode.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 Documentation/doc-guide/sphinx.rst |  18 +++++
 tools/docs/sphinx-pre-install      | 110 +++++++++++++++++++++++++++++
 2 files changed, 128 insertions(+)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 51c370260..1e105542a 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -131,6 +131,24 @@ It supports two optional parameters:
 ``--no-virtualenv``
 	Use OS packaging for Sphinx instead of Python virtual environment.
 
+macOS uses a case-insensitive APFS volume by default, but the kernel tree
+contains file names that differ only in case. Before cloning the tree, use
+``diskutil apfs list`` to find the APFS container identifier, replace
+``diskX`` below with that identifier, and create an additional case-sensitive
+volume with::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+On macOS, the script uses Homebrew for system dependencies. Homebrew
+commands are printed without ``sudo``. The PDF toolchain is provided by the
+``mactex-no-gui`` cask, while the required DejaVu and Noto CJK fonts are
+installed from Homebrew font casks; use ``--no-pdf`` when only building HTML
+documentation. After installing MacTeX, restart the terminal or run
+``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visible.
+The default virtualenv mode is recommended on macOS because PyYAML is
+installed from ``Documentation/sphinx/requirements.txt`` rather than from a
+Homebrew formula.
+
 Installing Sphinx Minimal Version
 ---------------------------------
 
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 965c9b093..1956f1369 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -518,6 +518,24 @@ class MissingCheckers(AncillaryMethods):
         a decent coverage.
         """
 
+        if sys.platform == "darwin":
+            sw_vers = self.which("sw_vers")
+            if sw_vers:
+                try:
+                    result = self.run(
+                        [sw_vers, "-productVersion"],
+                        capture_output=True,
+                        text=True,
+                        check=True,
+                    )
+                    version = result.stdout.strip()
+                    if version:
+                        return f"macOS {version}"
+                except (subprocess.CalledProcessError, FileNotFoundError):
+                    pass
+
+            return "macOS"
+
         system_release = ""
 
         if self.which("lsb_release"):
@@ -716,6 +734,93 @@ class SphinxDependencyChecker(MissingCheckers):
 
         return self.get_install_progs(progs, "apt-get install")
 
+    def give_macos_hints(self):
+        """Provide package installation hints for macOS using Homebrew."""
+        progs = {
+            "Pod::Usage":    "perl",
+            "convert":       "imagemagick",
+            "dot":           "graphviz",
+            "ensurepip":     "python",
+            "python-sphinx": "sphinx-doc",
+            "rsvg-convert":   "librsvg",
+            "xelatex":        "mactex-no-gui",
+            "latexmk":        "mactex-no-gui",
+        }
+
+        if self.pdf:
+            font_dirs = [
+                os.path.expanduser("~/Library/Fonts"),
+                "/Library/Fonts",
+                "/System/Library/Fonts",
+            ]
+            pdf_fonts = {
+                "font-dejavu": ["DejaVuSans.ttf"],
+                "font-noto-sans-cjk": ["NotoSansCJK.ttc"],
+            }
+
+            for package, names in pdf_fonts.items():
+                files = [
+                    os.path.join(font_dir, name)
+                    for font_dir in font_dirs
+                    for name in names
+                ]
+                self.check_missing_file(files, package, DepManager.PDF_MANDATORY)
+
+        install = self.deps.check_missing(progs)
+
+        if self.verbose_warn_install:
+            self.deps.warn_install()
+
+        if not install:
+            return None
+
+        formulae = set()
+        casks = set()
+        notes = []
+        for package in install.split():
+            if package == "yaml":
+                notes.append(
+                    "PyYAML is not provided as a Homebrew formula. Use the "
+                    "default virtualenv mode so it is installed from "
+                    "Documentation/sphinx/requirements.txt."
+                )
+                continue
+
+            if package == "mactex-no-gui" or package.startswith("font-"):
+                casks.add(package)
+            else:
+                formulae.add(package)
+
+        commands = []
+        if formulae:
+            commands.append("\tbrew install " + " ".join(sorted(formulae)))
+        if casks:
+            commands.append("\tbrew install --cask " + " ".join(sorted(casks)))
+
+        if not commands:
+            self.distro_msg = "\n".join(notes)
+            return None
+
+        if not self.which("brew"):
+            notes.append(
+                "Homebrew is needed to install the missing dependencies. "
+                "Install it from https://brew.sh/ and re-run this script."
+            )
+            self.distro_msg = "\n".join(notes)
+            return None
+
+        if "mactex-no-gui" in casks:
+            notes.append(
+                "After installing MacTeX, restart the terminal or run:\n"
+                "\teval \"$(/usr/libexec/path_helper)\"\n"
+                "before re-running this script."
+            )
+
+        if notes:
+            self.distro_msg = "\n".join(notes)
+
+        return "\nYou should run:\n" + "\n".join(commands)
+
     def give_redhat_hints(self):
         """
         Provide package installation hints for RedHat-based distros
@@ -1138,6 +1243,8 @@ class SphinxDependencyChecker(MissingCheckers):
             re.compile("Kali"):                       self.give_debian_hints,
             re.compile("Mint"):                       self.give_debian_hints,
 
+            re.compile("macOS"):                      self.give_macos_hints,
+
             re.compile("openSUSE"):                   self.give_opensuse_hints,
 
             re.compile("Mageia"):                     self.give_mageia_hints,
@@ -1458,6 +1565,9 @@ class SphinxDependencyChecker(MissingCheckers):
         self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
         self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
 
+        # PyYAML is required by Documentation/sphinx/parser_yaml.py. The
+        # macOS installation hints explain that it is installed from the
+        # virtualenv requirements, rather than from a Homebrew formula.
         self.check_python_module("yaml")
 
         if self.pdf:
-- 
2.50.1 (Apple Git-155)

[PATCH v3 3/6] docs: sphinx-pre-install: check GNU Make version

[Chen Miao]

The kernel documentation build requires GNU Make 4.0 or newer, but the
Sphinx dependency checker only verifies that a make executable exists. This
lets incompatible make implementations pass the check and fail later during
the build.

Check the GNU Make version on all supported systems. Prefer a compatible
gmake command, which is how Homebrew provides GNU Make on macOS, and fall
back to make. Use the common kdoc detector so the dependency checker and
build wrapper apply the same selection logic. Document the requirement and
the macOS gmake invocation.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 Documentation/doc-guide/sphinx.rst |  4 +++-
 tools/docs/sphinx-pre-install      | 10 +++++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 1e105542a..4fb716e77 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -147,7 +147,9 @@ documentation. After installing MacTeX, restart the terminal or run
 ``eval "$(/usr/libexec/path_helper)"`` so its command-line tools are visible.
 The default virtualenv mode is recommended on macOS because PyYAML is
 installed from ``Documentation/sphinx/requirements.txt`` rather than from a
-Homebrew formula.
+Homebrew formula. The script also checks for GNU Make 4.0 or newer; when
+Homebrew provides it as ``gmake``, use ``gmake htmldocs`` instead of
+``make htmldocs``.
 
 Installing Sphinx Minimal Version
 ---------------------------------
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 1956f1369..7625ac5a4 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -37,6 +37,7 @@ import os.path
 src_dir = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, os.path.join(src_dir, '../lib/python'))
 from kdoc.python_version import PythonVersion
+from kdoc.gmake_detect import find_gmake
 
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
@@ -308,6 +309,13 @@ class MissingCheckers(AncillaryMethods):
 
         return None
 
+    def check_make(self):
+        """Check for GNU Make 4.0 or newer."""
+        if find_gmake(os.environ.get("MAKE")):
+            return
+
+        self.deps.add_package("make", DepManager.SYSTEM_MANDATORY)
+
     def check_perl_module(self, prog, dtype):
         """
         Does perl have a dependency? Is it available?
@@ -1559,7 +1567,7 @@ class SphinxDependencyChecker(MissingCheckers):
         # Check for needed programs/tools
         self.check_perl_module("Pod::Usage", DepManager.SYSTEM_MANDATORY)
 
-        self.check_program("make", DepManager.SYSTEM_MANDATORY)
+        self.check_make()
         self.check_program("which", DepManager.SYSTEM_MANDATORY)
 
         self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
-- 
2.50.1 (Apple Git-155)

[PATCH v3 4/6] docs: sphinx-build-wrapper: prefer gmake

[Chen Miao]

Homebrew installs GNU Make as gmake on macOS, but the Sphinx build
wrapper invokes make directly when generating Info and Rust
documentation. This can make the dependency check succeed while those
documentation targets still use an incompatible make implementation.

Honor MAKE when it names a compatible GNU Make. Otherwise check gmake and
then make, selecting the first GNU Make 4.0 or newer. Use the common kdoc
detector to keep this selection consistent with sphinx-pre-install.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 tools/docs/sphinx-build-wrapper | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 1bb962202..15c7e0938 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -63,6 +63,7 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
 from kdoc.python_version import PythonVersion
+from kdoc.gmake_detect import find_gmake
 from kdoc.latex_fonts import LatexFontChecker
 from jobserver import JobserverExec         # pylint: disable=C0413,C0411,E0401
 
@@ -97,6 +98,14 @@ class SphinxBuilder:
     with the Kernel.
     """
 
+    def get_make(self):
+        """Select the first GNU Make 4.0 or newer in preference order."""
+        make = find_gmake(self.env.get("MAKE"))
+        if make:
+            return make
+
+        sys.exit("GNU Make 4.0 or newer is required")
+
     def get_path(self, path, use_cwd=False, abs_path=False):
         """
         Ancillary routine to handle patches the right way, as shell does.
@@ -569,9 +578,10 @@ class SphinxBuilder:
         texinfo directory.
         """
 
+        make = self.get_make()
         for output_dir in output_dirs:
             try:
-                subprocess.run(["make", "info"], cwd=output_dir, check=True)
+                subprocess.run([make, "info"], cwd=output_dir, check=True)
             except subprocess.CalledProcessError as e:
                 sys.exit(f"Error generating info docs: {e}")
 
@@ -787,12 +797,11 @@ class SphinxBuilder:
 
         if rustdoc and target in ["htmldocs", "epubdocs"]:
             print("Building rust docs")
-            if "MAKE" in self.env:
-                cmd = [self.env["MAKE"]]
-            else:
-                cmd = ["make", "LLVM=1"]
-
-            cmd += [ "rustdoc"]
+            make = self.get_make()
+            cmd = [make]
+            if make != self.env.get("MAKE"):
+                cmd.append("LLVM=1")
+            cmd.append("rustdoc")
             if self.verbose:
                 print(" ".join(cmd))
 
-- 
2.50.1 (Apple Git-155)

[PATCH v3 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup

[Chen Miao]

Translate the macOS Sphinx dependency setup added to the English
documentation. Keep the translation in a separate patch so translation
status tooling can track the source change correctly.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 .../translations/zh_CN/doc-guide/sphinx.rst     | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 3375c6f3a..e6d42d970 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -110,6 +110,22 @@ PDF和LaTeX构建
 
 	使用Sphinx的系统打包，而不是Python虚拟环境。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷，而内核源码树中存在仅大小写
+不同的文件。克隆源码前，请用 ``diskutil apfs list`` 找到 APFS 容器标识符，
+将下面的 ``diskX`` 替换为该标识符，并创建一个额外的大小写敏感卷::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+在 macOS 上，该脚本使用 Homebrew 安装系统依赖，输出的 Homebrew 命令不需要
+``sudo``。PDF 工具链由 ``mactex-no-gui`` cask 提供，所需的 DejaVu 和 Noto CJK
+字体则通过 Homebrew font cask 安装；如果只构建 HTML 文档，请使用 ``--no-pdf``。
+安装 MacTeX 后，请重新启动终端，或运行
+``eval "$(/usr/libexec/path_helper)"`` 使命令行工具可见。macOS 用户建议使用
+默认的 Python 虚拟环境，因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装，而不是通过 Homebrew 安装。
+该脚本还会检查 GNU Make 4.0 或更高版本；如果 Homebrew 将其安装为
+``gmake``，请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
+
 Sphinx构建
 ==========
 
@@ -409,4 +425,3 @@ Documentation/doc-guide/kernel-doc.rst 。
    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
    </svg>
-
-- 
2.50.1 (Apple Git-155)

[PATCH v3 6/6] docs/zh_CN: how-to: document case-sensitive APFS setup

[Chen Miao]

The APFS volume used by macOS is case-insensitive by default, while the
kernel tree contains file names that differ only in case. Document the
diskutil commands needed to identify the APFS container and add a
case-sensitive volume before cloning the tree.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 Documentation/translations/zh_CN/how-to.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index 9ec2384e1..e1d3d2b8b 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -102,6 +102,14 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
 开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
 您通过 pip/pypi 安装最新版本 Sphinx。
 
+macOS 默认使用不区分文件名大小写的 APFS 卷，而内核源码树中存在仅大小写
+不同的文件。在执行 ``git clone`` 前，可在现有 APFS 容器中创建一个额外的大小写
+敏感卷（先用 ``diskutil apfs list`` 找到容器标识符，并将下面的 ``diskX`` 替换为该标识符）::
+
+	diskutil apfs addVolume diskX APFSX Linux
+
+然后将内核源码克隆到新卷中。
+
 如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
 sphinx 虚拟环境，即只需要执行::
 
-- 
2.50.1 (Apple Git-155)