[PATCH v1 0/2] docs: sphinx-pre-install: improve dependency checks

[PATCH v1 0/2] 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:

  - adds macOS/Homebrew dependency handling, including MacTeX cask support;
  - checks for GNU Make 4.0 or newer and recognizes Homebrew's ``gmake``; and
  - avoids printing an empty installation command when only PyYAML is missing.

Thanks,

Chen Miao

Chen Miao (2):
  docs: sphinx-pre-install: add macOS Homebrew support
  docs: sphinx-pre-install: check GNU Make version

 Documentation/doc-guide/sphinx.rst            |   9 ++
 .../translations/zh_CN/doc-guide/sphinx.rst   |   7 +
 Documentation/translations/zh_CN/how-to.rst   |   7 +
 tools/docs/sphinx-pre-install                 | 141 +++++++++++++++++-
 4 files changed, 162 insertions(+), 2 deletions(-)

-- 
2.50.1 (Apple Git-155)

[PATCH v1 1/2] 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 MacTeX as a cask without
sudo. Keep PyYAML in the virtual environment requirements because
Homebrew does not provide a PyYAML formula.

Document the macOS setup and the --no-pdf option.

Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
---
 Documentation/doc-guide/sphinx.rst            |  7 ++
 .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
 Documentation/translations/zh_CN/how-to.rst   |  6 ++
 tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
 4 files changed, 106 insertions(+), 1 deletion(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 51c370260..62aca56b8 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -131,6 +131,13 @@ It supports two optional parameters:
 ``--no-virtualenv``
 	Use OS packaging for Sphinx instead of Python virtual environment.
 
+On macOS, the script uses Homebrew for system dependencies. Homebrew
+commands are printed without ``sudo``. The PDF dependencies are provided by
+the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentation.
+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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 3375c6f3a..154142318 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -110,6 +110,11 @@ PDF和LaTeX构建
 
 	使用Sphinx的系统打包，而不是Python虚拟环境。
 
+在 macOS 上，该脚本使用 Homebrew 安装系统依赖，输出的 Homebrew 命令不需要
+``sudo``。PDF 依赖通过 ``mactex`` cask 提供；如果只构建 HTML 文档，请使用
+``--no-pdf``。macOS 用户建议使用默认的 Python 虚拟环境，因为 PyYAML 会从
+``Documentation/sphinx/requirements.txt`` 安装，而不是通过 Homebrew 安装。
+
 Sphinx构建
 ==========
 
diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index 9ec2384e1..e8c91d81a 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
 开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
 您通过 pip/pypi 安装最新版本 Sphinx。
 
+如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
+sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
+可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
+的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
+安装，而不是通过 Homebrew 安装。
+
 如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
 sphinx 虚拟环境，即只需要执行::
 
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 965c9b093..51a296cc7 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,69 @@ 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.
+
+        Homebrew formulae and casks must not be installed with sudo. MacTeX
+        is a cask, while the other dependencies are formulae.
+        """
+        if not self.which("brew"):
+            if not self.distro_msg:
+                self.deps.add_package("Homebrew", DepManager.SYSTEM_MANDATORY)
+                self.deps.check_missing({})
+                self.deps.warn_install()
+                self.distro_msg = \
+                    "Homebrew is required for macOS support. Install it from " \
+                    "https://brew.sh/ and re-run this script."
+            return None
+
+        progs = {
+            "Pod::Usage":    "perl",
+            "convert":       "imagemagick",
+            "dot":           "graphviz",
+            "ensurepip":     "python",
+            "python-sphinx": "sphinx-doc",
+            "rsvg-convert":   "librsvg",
+            "xelatex":        "mactex",
+            "latexmk":        "mactex",
+        }
+
+        install = self.deps.check_missing(progs)
+
+        if self.verbose_warn_install:
+            self.deps.warn_install()
+
+        if not install:
+            return None
+
+        formulae = set()
+        casks = set()
+        for prog in self.deps.missing:
+            if prog == "yaml":
+                self.distro_msg = \
+                    "PyYAML is not provided as a Homebrew formula. Use the " \
+                    "default virtualenv mode so it is installed from " \
+                    "Documentation/sphinx/requirements.txt."
+                continue
+
+            package = progs.get(prog, prog)
+            if package == "mactex":
+                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:
+            return None
+
+        return "\nYou should run:\n" + "\n".join(commands)
+
     def give_redhat_hints(self):
         """
         Provide package installation hints for RedHat-based distros
@@ -1138,6 +1219,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,7 +1541,11 @@ class SphinxDependencyChecker(MissingCheckers):
         self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
         self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
 
-        self.check_python_module("yaml")
+        # PyYAML is installed from Documentation/sphinx/requirements.txt in
+        # the virtualenv recommended on macOS. Homebrew does not provide a
+        # PyYAML formula, so do not ask for a nonexistent brew package here.
+        if not (sys.platform == "darwin" and self.virtualenv and self.need_pip):
+            self.check_python_module("yaml")
 
         if self.pdf:
             self.check_program("xelatex", DepManager.PDF_MANDATORY)
-- 
2.50.1 (Apple Git-155)

[PATCH v1 2/2] 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. If make is missing
or too old, report it as a missing dependency. Also accept a compatible
gmake command, which is how Homebrew provides GNU Make on macOS.

Document the requirement and the macOS gmake fallback.

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

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 62aca56b8..d9b9e025f 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -136,7 +136,9 @@ commands are printed without ``sudo``. The PDF dependencies are provided by
 the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentation.
 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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 154142318..93f27d35a 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -114,6 +114,8 @@ PDF和LaTeX构建
 ``sudo``。PDF 依赖通过 ``mactex`` cask 提供；如果只构建 HTML 文档，请使用
 ``--no-pdf``。macOS 用户建议使用默认的 Python 虚拟环境，因为 PyYAML 会从
 ``Documentation/sphinx/requirements.txt`` 安装，而不是通过 Homebrew 安装。
+脚本还会检查 GNU Make 4.0 或更高版本；如果 Homebrew 将其安装为 ``gmake``，
+请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
 
 Sphinx构建
 ==========
diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index e8c91d81a..84f277124 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -106,7 +106,8 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
 sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
 可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
 的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
-安装，而不是通过 Homebrew 安装。
+安装，而不是通过 Homebrew 安装。脚本还会检查 GNU Make 4.0 或更高版本；如果
+Homebrew 将其安装为 ``gmake``，请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
 
 如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
 sphinx 虚拟环境，即只需要执行::
diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
index 51a296cc7..079655078 100755
--- a/tools/docs/sphinx-pre-install
+++ b/tools/docs/sphinx-pre-install
@@ -40,6 +40,7 @@ from kdoc.python_version import PythonVersion
 
 RECOMMENDED_VERSION = PythonVersion("3.4.3").version
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
+MIN_MAKE_VERSION = PythonVersion("4.0").version
 
 
 class DepManager:
@@ -308,6 +309,55 @@ class MissingCheckers(AncillaryMethods):
 
         return None
 
+    def get_make_version(self, cmd):
+        """Get the GNU Make version, or None if cmd is not GNU Make."""
+        if not cmd:
+            return None
+
+        try:
+            result = self.run(
+                [cmd, "--version"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            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 check_make(self):
+        """Check for GNU Make 4.0 or newer."""
+        make = self.which("make")
+        version = self.get_make_version(make)
+
+        if version and version >= MIN_MAKE_VERSION:
+            return
+
+        # macOS commonly has an incompatible /usr/bin/make, while Homebrew
+        # installs GNU Make as gmake. Also accept gmake on other systems when
+        # it is the only compatible command available.
+        gmake = self.which("gmake")
+        gmake_version = self.get_make_version(gmake)
+        if gmake_version and gmake_version >= MIN_MAKE_VERSION:
+            make_name = os.path.basename(make) if make else "make"
+            gmake_name = os.path.basename(gmake)
+            make_ver = PythonVersion.ver_str(version) if version else "unknown"
+            gmake_ver = PythonVersion.ver_str(gmake_version)
+            print(
+                f"Note: {make_name} ({make_ver}) does not meet the GNU Make "
+                f"requirement; use {gmake_name} ({gmake_ver}) instead."
+            )
+            return
+
+        self.deps.add_package("make", DepManager.SYSTEM_MANDATORY)
+
     def check_perl_module(self, prog, dtype):
         """
         Does perl have a dependency? Is it available?
@@ -1535,7 +1585,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)

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Weijie Yuan]

Hi Miao,

On Sun, Aug 09, 2026 at 06:19:20PM +0800, Chen Miao wrote:
> 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 MacTeX as a cask without
> sudo. Keep PyYAML in the virtual environment requirements because
> Homebrew does not provide a PyYAML formula.
> 
> Document the macOS setup and the --no-pdf option.
> 
> Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> ---
>  Documentation/doc-guide/sphinx.rst            |  7 ++
>  .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
>  Documentation/translations/zh_CN/how-to.rst   |  6 ++
>  tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
>  4 files changed, 106 insertions(+), 1 deletion(-)
[...]
> diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> index 9ec2384e1..e8c91d81a 100644
> --- a/Documentation/translations/zh_CN/how-to.rst
> +++ b/Documentation/translations/zh_CN/how-to.rst
> @@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
>  开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
>  您通过 pip/pypi 安装最新版本 Sphinx。
>  
> +如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
> +sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
> +可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
> +的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> +安装，而不是通过 Homebrew 安装。

My question is perhaps quite stupid. (I'm not familiar with this part)

How can you make "git clone xxx/linux.git" done on your mac? I've tried
this before, but it seems that there's some format issue? macOS's
default APFS is case-insensitive.., so I guess you did some extra
settings? (like 'git clone --sparse' or 'git clone --filter=blob:none'?)
But my intuition and experience tell me that it won't be convenient ;-)

If so, an additional description for macOS users might be more
user-friendly, I guess? Since the how-to file aims to lower the
threshold of the process of translation. (While I don't know how many
macOS users are potential contributors.)

And another thing is that zh_CN would prefer splitting zh_CN
translations apart from the original English one in your patch. Because
there's a script to monitor the translation status.
(Better confirm this with zh_CN maintainers)

Thanks.


I haven't read this script carefully. Please feel free to ignore my
incorrect comments below.

> diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
> index 965c9b093..51a296cc7 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,69 @@ 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.
> +
> +        Homebrew formulae and casks must not be installed with sudo. MacTeX
> +        is a cask, while the other dependencies are formulae.
> +        """
> +        if not self.which("brew"):

Homebrew seems to be treated as a build dependency here, rather than as
the package manager used to provide installation hints.

If all actual documentation dependencies are already installed on a
macOS system without Homebrew, this adds Homebrew as SYSTEM_MANDATORY,
increments self.deps.need, and eventually makes the script exit with
Can't build as 1 mandatory dependency is missing, even though the
documentation can actually be built.

Could we first check whether there are any missing dependencies and only
complain about a missing brew when an installation hint is actually
needed? I don't think Homebrew itself should be added to self.deps.

> +            if not self.distro_msg:
> +                self.deps.add_package("Homebrew", DepManager.SYSTEM_MANDATORY)
> +                self.deps.check_missing({})
> +                self.deps.warn_install()
> +                self.distro_msg = \
> +                    "Homebrew is required for macOS support. Install it from " \
> +                    "https://brew.sh/ and re-run this script."
> +            return None
> +
> +        progs = {
> +            "Pod::Usage":    "perl",
> +            "convert":       "imagemagick",
> +            "dot":           "graphviz",
> +            "ensurepip":     "python",
> +            "python-sphinx": "sphinx-doc",
> +            "rsvg-convert":   "librsvg",
> +            "xelatex":        "mactex",
> +            "latexmk":        "mactex",

Nit & Non-blocking:

Btw, would 'mactex-no-gui' be a better fit here?

The documentation build only needs the TeX command-line tools, while the
regular mactex cask also installs the GUI applications (I forget whether
GUI is big or not, but I guess <1GB). mactex-no-gui still provides the
full TeX Live distribution, so it may avoid installing software that is
not needed for kernel documentation builds.

Not a blocker.

> +        }
> +
> +        install = self.deps.check_missing(progs)
> +
> +        if self.verbose_warn_install:
> +            self.deps.warn_install()
> +
> +        if not install:
> +            return None
> +
> +        formulae = set()
> +        casks = set()
> +        for prog in self.deps.missing:
> +            if prog == "yaml":
> +                self.distro_msg = \
> +                    "PyYAML is not provided as a Homebrew formula. Use the " \
> +                    "default virtualenv mode so it is installed from " \
> +                    "Documentation/sphinx/requirements.txt."
> +                continue
> +
> +            package = progs.get(prog, prog)
> +            if package == "mactex":
> +                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)))

One more thing about the MacTeX hint: after installing the mactex cask,
its command-line tools may not become visible in the current shell
immediately. Homebrew's cask notes say that the terminal needs to be
restarted, or eval "$(/usr/libexec/path_helper)" (Is it?) should be run.

Otherwise, a user who immediately re-runs sphinx-pre-install after
following this suggestion may still see xelatex and latexmk reported as
missing.

Would it make sense to mention this in the macOS installation hint?

> +
> +        if not commands:
> +            return None
> +
> +        return "\nYou should run:\n" + "\n".join(commands)
> +
>      def give_redhat_hints(self):
>          """
>          Provide package installation hints for RedHat-based distros
> @@ -1138,6 +1219,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,7 +1541,11 @@ class SphinxDependencyChecker(MissingCheckers):
>          self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
>          self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
>  
> -        self.check_python_module("yaml")
> +        # PyYAML is installed from Documentation/sphinx/requirements.txt in
> +        # the virtualenv recommended on macOS. Homebrew does not provide a
> +        # PyYAML formula, so do not ask for a nonexistent brew package here.
> +        if not (sys.platform == "darwin" and self.virtualenv and self.need_pip):
> +            self.check_python_module("yaml")
>  
>          if self.pdf:
>              self.check_program("xelatex", DepManager.PDF_MANDATORY)

Thanks.

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Dongliang Mu]

On 8/9/26 9:02 PM, Weijie Yuan wrote:
> Hi Miao,
>
> On Sun, Aug 09, 2026 at 06:19:20PM +0800, Chen Miao wrote:
>> 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 MacTeX as a cask without
>> sudo. Keep PyYAML in the virtual environment requirements because
>> Homebrew does not provide a PyYAML formula.
>>
>> Document the macOS setup and the --no-pdf option.
>>
>> Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
>> ---
>>   Documentation/doc-guide/sphinx.rst            |  7 ++
>>   .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
>>   Documentation/translations/zh_CN/how-to.rst   |  6 ++
>>   tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
>>   4 files changed, 106 insertions(+), 1 deletion(-)
> [...]
>> diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
>> index 9ec2384e1..e8c91d81a 100644
>> --- a/Documentation/translations/zh_CN/how-to.rst
>> +++ b/Documentation/translations/zh_CN/how-to.rst
>> @@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
>>   开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
>>   您通过 pip/pypi 安装最新版本 Sphinx。
>>   
>> +如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
>> +sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
>> +可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
>> +的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
>> +安装，而不是通过 Homebrew 安装。
> My question is perhaps quite stupid. (I'm not familiar with this part)
>
> How can you make "git clone xxx/linux.git" done on your mac? I've tried
> this before, but it seems that there's some format issue? macOS's
> default APFS is case-insensitive.., so I guess you did some extra
> settings? (like 'git clone --sparse' or 'git clone --filter=blob:none'?)
> But my intuition and experience tell me that it won't be convenient ;-)
For Mac OSX, you need to first establish a Case-sensitive APFS Volume, 
and in this volume you can execute thse commands.
>
> If so, an additional description for macOS users might be more
> user-friendly, I guess? Since the how-to file aims to lower the
> threshold of the process of translation. (While I don't know how many
> macOS users are potential contributors.)
I don't prefer to add many description about "how to start kernel 
development on Mac OS X". Some key parts should be enough.
>
> And another thing is that zh_CN would prefer splitting zh_CN
> translations apart from the original English one in your patch. Because
> there's a script to monitor the translation status.
> (Better confirm this with zh_CN maintainers)

This is a good suggestion. However, many minor changes of documentation 
contains EN and zh_CN in the same patch :(


For the script, l will comment in another email.

>
> Thanks.
>
>
> I haven't read this script carefully. Please feel free to ignore my
> incorrect comments below.
>
>> diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
>> index 965c9b093..51a296cc7 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,69 @@ 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.
>> +
>> +        Homebrew formulae and casks must not be installed with sudo. MacTeX
>> +        is a cask, while the other dependencies are formulae.
>> +        """
>> +        if not self.which("brew"):
> Homebrew seems to be treated as a build dependency here, rather than as
> the package manager used to provide installation hints.
>
> If all actual documentation dependencies are already installed on a
> macOS system without Homebrew, this adds Homebrew as SYSTEM_MANDATORY,
> increments self.deps.need, and eventually makes the script exit with
> Can't build as 1 mandatory dependency is missing, even though the
> documentation can actually be built.
>
> Could we first check whether there are any missing dependencies and only
> complain about a missing brew when an installation hint is actually
> needed? I don't think Homebrew itself should be added to self.deps.
>
>> +            if not self.distro_msg:
>> +                self.deps.add_package("Homebrew", DepManager.SYSTEM_MANDATORY)
>> +                self.deps.check_missing({})
>> +                self.deps.warn_install()
>> +                self.distro_msg = \
>> +                    "Homebrew is required for macOS support. Install it from " \
>> +                    "https://brew.sh/ and re-run this script."
>> +            return None
>> +
>> +        progs = {
>> +            "Pod::Usage":    "perl",
>> +            "convert":       "imagemagick",
>> +            "dot":           "graphviz",
>> +            "ensurepip":     "python",
>> +            "python-sphinx": "sphinx-doc",
>> +            "rsvg-convert":   "librsvg",
>> +            "xelatex":        "mactex",
>> +            "latexmk":        "mactex",
> Nit & Non-blocking:
>
> Btw, would 'mactex-no-gui' be a better fit here?
>
> The documentation build only needs the TeX command-line tools, while the
> regular mactex cask also installs the GUI applications (I forget whether
> GUI is big or not, but I guess <1GB). mactex-no-gui still provides the
> full TeX Live distribution, so it may avoid installing software that is
> not needed for kernel documentation builds.
>
> Not a blocker.
>
>> +        }
>> +
>> +        install = self.deps.check_missing(progs)
>> +
>> +        if self.verbose_warn_install:
>> +            self.deps.warn_install()
>> +
>> +        if not install:
>> +            return None
>> +
>> +        formulae = set()
>> +        casks = set()
>> +        for prog in self.deps.missing:
>> +            if prog == "yaml":
>> +                self.distro_msg = \
>> +                    "PyYAML is not provided as a Homebrew formula. Use the " \
>> +                    "default virtualenv mode so it is installed from " \
>> +                    "Documentation/sphinx/requirements.txt."
>> +                continue
>> +
>> +            package = progs.get(prog, prog)
>> +            if package == "mactex":
>> +                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)))
> One more thing about the MacTeX hint: after installing the mactex cask,
> its command-line tools may not become visible in the current shell
> immediately. Homebrew's cask notes say that the terminal needs to be
> restarted, or eval "$(/usr/libexec/path_helper)" (Is it?) should be run.
>
> Otherwise, a user who immediately re-runs sphinx-pre-install after
> following this suggestion may still see xelatex and latexmk reported as
> missing.
>
> Would it make sense to mention this in the macOS installation hint?
>
>> +
>> +        if not commands:
>> +            return None
>> +
>> +        return "\nYou should run:\n" + "\n".join(commands)
>> +
>>       def give_redhat_hints(self):
>>           """
>>           Provide package installation hints for RedHat-based distros
>> @@ -1138,6 +1219,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,7 +1541,11 @@ class SphinxDependencyChecker(MissingCheckers):
>>           self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
>>           self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
>>   
>> -        self.check_python_module("yaml")
>> +        # PyYAML is installed from Documentation/sphinx/requirements.txt in
>> +        # the virtualenv recommended on macOS. Homebrew does not provide a
>> +        # PyYAML formula, so do not ask for a nonexistent brew package here.
>> +        if not (sys.platform == "darwin" and self.virtualenv and self.need_pip):
>> +            self.check_python_module("yaml")
>>   
>>           if self.pdf:
>>               self.check_program("xelatex", DepManager.PDF_MANDATORY)
> Thanks.

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Weijie Yuan]

On Sun, Aug 09, 2026 at 09:21:45PM +0800, Dongliang Mu wrote:
> 
> On 8/9/26 9:02 PM, Weijie Yuan wrote:
> > Hi Miao,
> > 
> > On Sun, Aug 09, 2026 at 06:19:20PM +0800, Chen Miao wrote:
> > > 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 MacTeX as a cask without
> > > sudo. Keep PyYAML in the virtual environment requirements because
> > > Homebrew does not provide a PyYAML formula.
> > > 
> > > Document the macOS setup and the --no-pdf option.
> > > 
> > > Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> > > ---
> > >   Documentation/doc-guide/sphinx.rst            |  7 ++
> > >   .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
> > >   Documentation/translations/zh_CN/how-to.rst   |  6 ++
> > >   tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
> > >   4 files changed, 106 insertions(+), 1 deletion(-)
> > [...]
> > > diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> > > index 9ec2384e1..e8c91d81a 100644
> > > --- a/Documentation/translations/zh_CN/how-to.rst
> > > +++ b/Documentation/translations/zh_CN/how-to.rst
> > > @@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
> > >   开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
> > >   您通过 pip/pypi 安装最新版本 Sphinx。
> > > +如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
> > > +sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
> > > +可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
> > > +的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> > > +安装，而不是通过 Homebrew 安装。
> > My question is perhaps quite stupid. (I'm not familiar with this part)
> > 
> > How can you make "git clone xxx/linux.git" done on your mac? I've tried
> > this before, but it seems that there's some format issue? macOS's
> > default APFS is case-insensitive.., so I guess you did some extra
> > settings? (like 'git clone --sparse' or 'git clone --filter=blob:none'?)
> > But my intuition and experience tell me that it won't be convenient ;-)
> 
> For Mac OSX, you need to first establish a Case-sensitive APFS Volume, and
> in this volume you can execute thse commands.

Yes. So what I mean is: for documentation that tries to keep the barrier
to entry for new contributors as low as possible, if we are going to
introduce macOS-specific instructions here, would it be worth mentioning
this as well (i.e. the case-sensitivity issue)?

That said, if someone is already doing this kind of work, they probably
do not need much explanation about it anyway.

> > If so, an additional description for macOS users might be more
> > user-friendly, I guess? Since the how-to file aims to lower the
> > threshold of the process of translation. (While I don't know how many
> > macOS users are potential contributors.)
> 
> I don't prefer to add many description about "how to start kernel
> development on Mac OS X". Some key parts should be enough.

Yes. Agreed.

> > And another thing is that zh_CN would prefer splitting zh_CN
> > translations apart from the original English one in your patch. Because
> > there's a script to monitor the translation status.
> > (Better confirm this with zh_CN maintainers)
> 
> This is a good suggestion. However, many minor changes of documentation
> contains EN and zh_CN in the same patch :(

Then I guess we'll just have to wait for the next patch adding a new
translation to verify the statistics produced by the script.

Thanks.

Re: [PATCH v1 2/2] docs: sphinx-pre-install: check GNU Make version

[Mauro Carvalho Chehab]

On Sun,  9 Aug 2026 18:19:21 +0800
Chen Miao <chenmiao.ku@gmail.com> wrote:

> 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. If make is missing
> or too old, report it as a missing dependency. Also accept a compatible
> gmake command, which is how Homebrew provides GNU Make on macOS.
> 
> Document the requirement and the macOS gmake fallback.
> 
> Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> ---
>  Documentation/doc-guide/sphinx.rst            |  4 +-
>  .../translations/zh_CN/doc-guide/sphinx.rst   |  2 +
>  Documentation/translations/zh_CN/how-to.rst   |  3 +-
>  tools/docs/sphinx-pre-install                 | 52 ++++++++++++++++++-
>  4 files changed, 58 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 62aca56b8..d9b9e025f 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -136,7 +136,9 @@ commands are printed without ``sudo``. The PDF dependencies are provided by
>  the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentation.
>  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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> index 154142318..93f27d35a 100644
> --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> @@ -114,6 +114,8 @@ PDF和LaTeX构建
>  ``sudo``。PDF 依赖通过 ``mactex`` cask 提供；如果只构建 HTML 文档，请使用
>  ``--no-pdf``。macOS 用户建议使用默认的 Python 虚拟环境，因为 PyYAML 会从
>  ``Documentation/sphinx/requirements.txt`` 安装，而不是通过 Homebrew 安装。
> +脚本还会检查 GNU Make 4.0 或更高版本；如果 Homebrew 将其安装为 ``gmake``，
> +请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
>  
>  Sphinx构建
>  ==========
> diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> index e8c91d81a..84f277124 100644
> --- a/Documentation/translations/zh_CN/how-to.rst
> +++ b/Documentation/translations/zh_CN/how-to.rst
> @@ -106,7 +106,8 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
>  sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
>  可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
>  的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> -安装，而不是通过 Homebrew 安装。
> +安装，而不是通过 Homebrew 安装。脚本还会检查 GNU Make 4.0 或更高版本；如果
> +Homebrew 将其安装为 ``gmake``，请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
>  
>  如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
>  sphinx 虚拟环境，即只需要执行::
> diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
> index 51a296cc7..079655078 100755
> --- a/tools/docs/sphinx-pre-install
> +++ b/tools/docs/sphinx-pre-install
> @@ -40,6 +40,7 @@ from kdoc.python_version import PythonVersion
>  
>  RECOMMENDED_VERSION = PythonVersion("3.4.3").version
>  MIN_PYTHON_VERSION = PythonVersion("3.7").version
> +MIN_MAKE_VERSION = PythonVersion("4.0").version
>  
>  
>  class DepManager:
> @@ -308,6 +309,55 @@ class MissingCheckers(AncillaryMethods):
>  
>          return None
>  
> +    def get_make_version(self, cmd):
> +        """Get the GNU Make version, or None if cmd is not GNU Make."""
> +        if not cmd:
> +            return None
> +
> +        try:
> +            result = self.run(
> +                [cmd, "--version"],
> +                capture_output=True,
> +                text=True,
> +                check=True,
> +            )
> +        except (subprocess.CalledProcessError, FileNotFoundError):
> +            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 check_make(self):
> +        """Check for GNU Make 4.0 or newer."""
> +        make = self.which("make")
> +        version = self.get_make_version(make)

I would invert the check: test first for "gmake", and then for "make".

Lots of Linux distros have an alias for gmake, like on Fedora:

	lrwxrwxrwx 1 root root        4 Apr 24 21:33 /usr/bin/gmake -> make
	-rwxr-xr-x 1 root root   287384 Apr 24 21:33 /usr/bin/make

Yet, I would do it on a different way:

	make = self.which("gmake")
	if not make:
		make = self.which("make")

	version = self.get_make_version(make)

This should simplify the code a little bit.

> +
> +        if version and version >= MIN_MAKE_VERSION:
> +            return
> +
> +        # macOS commonly has an incompatible /usr/bin/make, while Homebrew
> +        # installs GNU Make as gmake. Also accept gmake on other systems when
> +        # it is the only compatible command available.
> +        gmake = self.which("gmake")
> +        gmake_version = self.get_make_version(gmake)
> +        if gmake_version and gmake_version >= MIN_MAKE_VERSION:
> +            make_name = os.path.basename(make) if make else "make"
> +            gmake_name = os.path.basename(gmake)
> +            make_ver = PythonVersion.ver_str(version) if version else "unknown"
> +            gmake_ver = PythonVersion.ver_str(gmake_version)
> +            print(
> +                f"Note: {make_name} ({make_ver}) does not meet the GNU Make "
> +                f"requirement; use {gmake_name} ({gmake_ver}) instead."
> +            )
> +            return

With that, you probably can remove most of the above.

Btw, you likely need to teach tools/docs/sphinx-build-wrapper
to also consider gmake binary, as it can run make internally
to generate info and Rust docs.

Thanks,
Mauro

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Chen Miao]

Weijie Yuan <wy@wyuan.org> 于2026年8月9日周日 21:02写道：
>
> Hi Miao,
>
> On Sun, Aug 09, 2026 at 06:19:20PM +0800, Chen Miao wrote:
> > 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 MacTeX as a cask without
> > sudo. Keep PyYAML in the virtual environment requirements because
> > Homebrew does not provide a PyYAML formula.
> >
> > Document the macOS setup and the --no-pdf option.
> >
> > Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> > ---
> >  Documentation/doc-guide/sphinx.rst            |  7 ++
> >  .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
> >  Documentation/translations/zh_CN/how-to.rst   |  6 ++
> >  tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
> >  4 files changed, 106 insertions(+), 1 deletion(-)
> [...]
> > diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> > index 9ec2384e1..e8c91d81a 100644
> > --- a/Documentation/translations/zh_CN/how-to.rst
> > +++ b/Documentation/translations/zh_CN/how-to.rst
> > @@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
> >  开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
> >  您通过 pip/pypi 安装最新版本 Sphinx。
> >
> > +如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
> > +sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
> > +可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
> > +的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> > +安装，而不是通过 Homebrew 安装。
>
> My question is perhaps quite stupid. (I'm not familiar with this part)
>
> How can you make "git clone xxx/linux.git" done on your mac? I've tried
> this before, but it seems that there's some format issue? macOS's
> default APFS is case-insensitive.., so I guess you did some extra
> settings? (like 'git clone --sparse' or 'git clone --filter=blob:none'?)
> But my intuition and experience tell me that it won't be convenient ;-)
>
> If so, an additional description for macOS users might be more
> user-friendly, I guess? Since the how-to file aims to lower the
> threshold of the process of translation. (While I don't know how many
> macOS users are potential contributors.)
>
> And another thing is that zh_CN would prefer splitting zh_CN
> translations apart from the original English one in your patch. Because
> there's a script to monitor the translation status.
> (Better confirm this with zh_CN maintainers)
>
> Thanks.
>
Regarding APFS, I'll reply to that together in response to your latest email.
I see that you and the other reviewer have reached a consensus.

In the next revision of the patch, I'll split the English and Chinese versions
into separate patches. I agree that this would indeed be better.
>
> I haven't read this script carefully. Please feel free to ignore my
> incorrect comments below.
>
> > diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
> > index 965c9b093..51a296cc7 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,69 @@ 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.
> > +
> > +        Homebrew formulae and casks must not be installed with sudo. MacTeX
> > +        is a cask, while the other dependencies are formulae.
> > +        """
> > +        if not self.which("brew"):
>
> Homebrew seems to be treated as a build dependency here, rather than as
> the package manager used to provide installation hints.
>
> If all actual documentation dependencies are already installed on a
> macOS system without Homebrew, this adds Homebrew as SYSTEM_MANDATORY,
> increments self.deps.need, and eventually makes the script exit with
> Can't build as 1 mandatory dependency is missing, even though the
> documentation can actually be built.
>
> Could we first check whether there are any missing dependencies and only
> complain about a missing brew when an installation hint is actually
> needed? I don't think Homebrew itself should be added to self.deps.
>
I think you're right — Homebrew is not a required dependency. We should only
suggest using `brew` to install the necessary dependencies when we detect that
they are missing.
>
> > +            if not self.distro_msg:
> > +                self.deps.add_package("Homebrew", DepManager.SYSTEM_MANDATORY)
> > +                self.deps.check_missing({})
> > +                self.deps.warn_install()
> > +                self.distro_msg = \
> > +                    "Homebrew is required for macOS support. Install it from " \
> > +                    "https://brew.sh/ and re-run this script."
> > +            return None
> > +
> > +        progs = {
> > +            "Pod::Usage":    "perl",
> > +            "convert":       "imagemagick",
> > +            "dot":           "graphviz",
> > +            "ensurepip":     "python",
> > +            "python-sphinx": "sphinx-doc",
> > +            "rsvg-convert":   "librsvg",
> > +            "xelatex":        "mactex",
> > +            "latexmk":        "mactex",
>
> Nit & Non-blocking:
>
> Btw, would 'mactex-no-gui' be a better fit here?
>
> The documentation build only needs the TeX command-line tools, while the
> regular mactex cask also installs the GUI applications (I forget whether
> GUI is big or not, but I guess <1GB). mactex-no-gui still provides the
> full TeX Live distribution, so it may avoid installing software that is
> not needed for kernel documentation builds.
>
Agree.
>
> Not a blocker.
>
> > +        }
> > +
> > +        install = self.deps.check_missing(progs)
> > +
> > +        if self.verbose_warn_install:
> > +            self.deps.warn_install()
> > +
> > +        if not install:
> > +            return None
> > +
> > +        formulae = set()
> > +        casks = set()
> > +        for prog in self.deps.missing:
> > +            if prog == "yaml":
> > +                self.distro_msg = \
> > +                    "PyYAML is not provided as a Homebrew formula. Use the " \
> > +                    "default virtualenv mode so it is installed from " \
> > +                    "Documentation/sphinx/requirements.txt."
> > +                continue
> > +
> > +            package = progs.get(prog, prog)
> > +            if package == "mactex":
> > +                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)))
>
> One more thing about the MacTeX hint: after installing the mactex cask,
> its command-line tools may not become visible in the current shell
> immediately. Homebrew's cask notes say that the terminal needs to be
> restarted, or eval "$(/usr/libexec/path_helper)" (Is it?) should be run.
>
> Otherwise, a user who immediately re-runs sphinx-pre-install after
> following this suggestion may still see xelatex and latexmk reported as
> missing.
>
> Would it make sense to mention this in the macOS installation hint?
>
Sure, nice tips.

Thanks,
Chen Miao
>
> > +
> > +        if not commands:
> > +            return None
> > +
> > +        return "\nYou should run:\n" + "\n".join(commands)
> > +
> >      def give_redhat_hints(self):
> >          """
> >          Provide package installation hints for RedHat-based distros
> > @@ -1138,6 +1219,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,7 +1541,11 @@ class SphinxDependencyChecker(MissingCheckers):
> >          self.check_program("dot", DepManager.SYSTEM_OPTIONAL)
> >          self.check_program("convert", DepManager.SYSTEM_OPTIONAL)
> >
> > -        self.check_python_module("yaml")
> > +        # PyYAML is installed from Documentation/sphinx/requirements.txt in
> > +        # the virtualenv recommended on macOS. Homebrew does not provide a
> > +        # PyYAML formula, so do not ask for a nonexistent brew package here.
> > +        if not (sys.platform == "darwin" and self.virtualenv and self.need_pip):
> > +            self.check_python_module("yaml")
> >
> >          if self.pdf:
> >              self.check_program("xelatex", DepManager.PDF_MANDATORY)
>
> Thanks.

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Chen Miao]

Weijie Yuan <wy@wyuan.org> 于2026年8月9日周日 22:12写道：
>
> On Sun, Aug 09, 2026 at 09:21:45PM +0800, Dongliang Mu wrote:
> >
> > On 8/9/26 9:02 PM, Weijie Yuan wrote:
> > > Hi Miao,
> > >
> > > On Sun, Aug 09, 2026 at 06:19:20PM +0800, Chen Miao wrote:
> > > > 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 MacTeX as a cask without
> > > > sudo. Keep PyYAML in the virtual environment requirements because
> > > > Homebrew does not provide a PyYAML formula.
> > > >
> > > > Document the macOS setup and the --no-pdf option.
> > > >
> > > > Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> > > > ---
> > > >   Documentation/doc-guide/sphinx.rst            |  7 ++
> > > >   .../translations/zh_CN/doc-guide/sphinx.rst   |  5 ++
> > > >   Documentation/translations/zh_CN/how-to.rst   |  6 ++
> > > >   tools/docs/sphinx-pre-install                 | 89 ++++++++++++++++++-
> > > >   4 files changed, 106 insertions(+), 1 deletion(-)
> > > [...]
> > > > diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> > > > index 9ec2384e1..e8c91d81a 100644
> > > > --- a/Documentation/translations/zh_CN/how-to.rst
> > > > +++ b/Documentation/translations/zh_CN/how-to.rst
> > > > @@ -102,6 +102,12 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
> > > >   开头的命令。**请注意**，最新版本 Sphinx 的文档编译速度有极大提升，强烈建议
> > > >   您通过 pip/pypi 安装最新版本 Sphinx。
> > > > +如果您使用 macOS，脚本会使用 Homebrew 输出安装命令，Homebrew 命令不需要
> > > > +sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
> > > > +可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
> > > > +的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> > > > +安装，而不是通过 Homebrew 安装。
> > > My question is perhaps quite stupid. (I'm not familiar with this part)
> > >
> > > How can you make "git clone xxx/linux.git" done on your mac? I've tried
> > > this before, but it seems that there's some format issue? macOS's
> > > default APFS is case-insensitive.., so I guess you did some extra
> > > settings? (like 'git clone --sparse' or 'git clone --filter=blob:none'?)
> > > But my intuition and experience tell me that it won't be convenient ;-)
> >
> > For Mac OSX, you need to first establish a Case-sensitive APFS Volume, and
> > in this volume you can execute thse commands.
>
> Yes. So what I mean is: for documentation that tries to keep the barrier
> to entry for new contributors as low as possible, if we are going to
> introduce macOS-specific instructions here, would it be worth mentioning
> this as well (i.e. the case-sensitivity issue)?
>
> That said, if someone is already doing this kind of work, they probably
> do not need much explanation about it anyway.
>
> > > If so, an additional description for macOS users might be more
> > > user-friendly, I guess? Since the how-to file aims to lower the
> > > threshold of the process of translation. (While I don't know how many
> > > macOS users are potential contributors.)
> >
> > I don't prefer to add many description about "how to start kernel
> > development on Mac OS X". Some key parts should be enough.
>
> Yes. Agreed.
>
Thanks for the clarification. I'll first check whether the kernel documentation
already has something like a "macOS kernel development guide." If not, I think
it might be worth documenting this.

In particular, macOS uses a case-insensitive APFS volume by default, which can
cause unexpected problems for newcomers working with the Linux kernel source
tree. It would be unfortunate if there were no documentation covering the
things developers need to be aware of when doing kernel development on macOS.
That said, I suspect this would be better handled in a separate patch series.

Of course, if such documentation already exists, then that's even better, and
there would be no need to add another one.

My main concern is that, if there are currently no macOS-specific notes in the
kernel documentation, some important details may remain implicit knowledge
among experienced macOS users rather than being documented for newcomers.

Thanks,
Chen Miao
>
> > > And another thing is that zh_CN would prefer splitting zh_CN
> > > translations apart from the original English one in your patch. Because
> > > there's a script to monitor the translation status.
> > > (Better confirm this with zh_CN maintainers)
> >
> > This is a good suggestion. However, many minor changes of documentation
> > contains EN and zh_CN in the same patch :(
>
> Then I guess we'll just have to wait for the next patch adding a new
> translation to verify the statistics produced by the script.
>
> Thanks.

Re: [PATCH v1 2/2] docs: sphinx-pre-install: check GNU Make version

[Chen Miao]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 于2026年8月10日周一 01:18写道：
>
> On Sun,  9 Aug 2026 18:19:21 +0800
> Chen Miao <chenmiao.ku@gmail.com> wrote:
>
> > 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. If make is missing
> > or too old, report it as a missing dependency. Also accept a compatible
> > gmake command, which is how Homebrew provides GNU Make on macOS.
> >
> > Document the requirement and the macOS gmake fallback.
> >
> > Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> > ---
> >  Documentation/doc-guide/sphinx.rst            |  4 +-
> >  .../translations/zh_CN/doc-guide/sphinx.rst   |  2 +
> >  Documentation/translations/zh_CN/how-to.rst   |  3 +-
> >  tools/docs/sphinx-pre-install                 | 52 ++++++++++++++++++-
> >  4 files changed, 58 insertions(+), 3 deletions(-)
> >
> > diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> > index 62aca56b8..d9b9e025f 100644
> > --- a/Documentation/doc-guide/sphinx.rst
> > +++ b/Documentation/doc-guide/sphinx.rst
> > @@ -136,7 +136,9 @@ commands are printed without ``sudo``. The PDF dependencies are provided by
> >  the ``mactex`` cask; use ``--no-pdf`` when only building HTML documentation.
> >  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/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> > index 154142318..93f27d35a 100644
> > --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> > +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> > @@ -114,6 +114,8 @@ PDF和LaTeX构建
> >  ``sudo``。PDF 依赖通过 ``mactex`` cask 提供；如果只构建 HTML 文档，请使用
> >  ``--no-pdf``。macOS 用户建议使用默认的 Python 虚拟环境，因为 PyYAML 会从
> >  ``Documentation/sphinx/requirements.txt`` 安装，而不是通过 Homebrew 安装。
> > +脚本还会检查 GNU Make 4.0 或更高版本；如果 Homebrew 将其安装为 ``gmake``，
> > +请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
> >
> >  Sphinx构建
> >  ==========
> > diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> > index e8c91d81a..84f277124 100644
> > --- a/Documentation/translations/zh_CN/how-to.rst
> > +++ b/Documentation/translations/zh_CN/how-to.rst
> > @@ -106,7 +106,8 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
> >  sudo。PDF 构建所需的 MacTeX 通过 Homebrew cask 安装；如果只构建 HTML 文档，
> >  可以执行 ``./tools/docs/sphinx-pre-install --no-pdf``。macOS 用户建议使用默认
> >  的 Python 虚拟环境，因为 PyYAML 会从 ``Documentation/sphinx/requirements.txt``
> > -安装，而不是通过 Homebrew 安装。
> > +安装，而不是通过 Homebrew 安装。脚本还会检查 GNU Make 4.0 或更高版本；如果
> > +Homebrew 将其安装为 ``gmake``，请使用 ``gmake htmldocs``，而不是 ``make htmldocs``。
> >
> >  如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
> >  sphinx 虚拟环境，即只需要执行::
> > diff --git a/tools/docs/sphinx-pre-install b/tools/docs/sphinx-pre-install
> > index 51a296cc7..079655078 100755
> > --- a/tools/docs/sphinx-pre-install
> > +++ b/tools/docs/sphinx-pre-install
> > @@ -40,6 +40,7 @@ from kdoc.python_version import PythonVersion
> >
> >  RECOMMENDED_VERSION = PythonVersion("3.4.3").version
> >  MIN_PYTHON_VERSION = PythonVersion("3.7").version
> > +MIN_MAKE_VERSION = PythonVersion("4.0").version
> >
> >
> >  class DepManager:
> > @@ -308,6 +309,55 @@ class MissingCheckers(AncillaryMethods):
> >
> >          return None
> >
> > +    def get_make_version(self, cmd):
> > +        """Get the GNU Make version, or None if cmd is not GNU Make."""
> > +        if not cmd:
> > +            return None
> > +
> > +        try:
> > +            result = self.run(
> > +                [cmd, "--version"],
> > +                capture_output=True,
> > +                text=True,
> > +                check=True,
> > +            )
> > +        except (subprocess.CalledProcessError, FileNotFoundError):
> > +            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 check_make(self):
> > +        """Check for GNU Make 4.0 or newer."""
> > +        make = self.which("make")
> > +        version = self.get_make_version(make)
>
> I would invert the check: test first for "gmake", and then for "make".
>
> Lots of Linux distros have an alias for gmake, like on Fedora:
>
>         lrwxrwxrwx 1 root root        4 Apr 24 21:33 /usr/bin/gmake -> make
>         -rwxr-xr-x 1 root root   287384 Apr 24 21:33 /usr/bin/make
>
> Yet, I would do it on a different way:
>
>         make = self.which("gmake")
>         if not make:
>                 make = self.which("make")
>
>         version = self.get_make_version(make)
>
> This should simplify the code a little bit.
>
Yes, I overlooked that. I'll fix it in the next revision.
>
> > +
> > +        if version and version >= MIN_MAKE_VERSION:
> > +            return
> > +
> > +        # macOS commonly has an incompatible /usr/bin/make, while Homebrew
> > +        # installs GNU Make as gmake. Also accept gmake on other systems when
> > +        # it is the only compatible command available.
> > +        gmake = self.which("gmake")
> > +        gmake_version = self.get_make_version(gmake)
> > +        if gmake_version and gmake_version >= MIN_MAKE_VERSION:
> > +            make_name = os.path.basename(make) if make else "make"
> > +            gmake_name = os.path.basename(gmake)
> > +            make_ver = PythonVersion.ver_str(version) if version else "unknown"
> > +            gmake_ver = PythonVersion.ver_str(gmake_version)
> > +            print(
> > +                f"Note: {make_name} ({make_ver}) does not meet the GNU Make "
> > +                f"requirement; use {gmake_name} ({gmake_ver}) instead."
> > +            )
> > +            return
>
> With that, you probably can remove most of the above.
>
> Btw, you likely need to teach tools/docs/sphinx-build-wrapper
> to also consider gmake binary, as it can run make internally
> to generate info and Rust docs.
>
> Thanks,
> Mauro
>
I'll add a separate patch in the next series to handle
tools/docs/sphinx-build-wrapper.

Thanks,
Chen Miao

Re: [PATCH v1 1/2] docs: sphinx-pre-install: add macOS Homebrew support

[Jonathan Corbet]

Chen Miao <chenmiao.ku@gmail.com> writes:

> Thanks for the clarification. I'll first check whether the kernel documentation
> already has something like a "macOS kernel development guide." If not, I think
> it might be worth documenting this.
>
> In particular, macOS uses a case-insensitive APFS volume by default, which can
> cause unexpected problems for newcomers working with the Linux kernel source
> tree. It would be unfortunate if there were no documentation covering the
> things developers need to be aware of when doing kernel development on macOS.
> That said, I suspect this would be better handled in a separate patch series.
>
> Of course, if such documentation already exists, then that's even better, and
> there would be no need to add another one.

There is no such guide now.

Correct me if I'm wrong, but I *think* that absence reflects the fact
that Linux kernel development is mostly done on Linux systems?

We can certainly add such a guide if somebody is willing to write it,
and if it would be useful to people.

Thanks,

jon