[PATCH v2 0/5] docs: sphinx-pre-install: improve dependency checks

[PATCH v2 0/5] 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 v2:

- do not treat Homebrew itself as a mandatory build dependency;
- use the mactex-no-gui cask, install the required DejaVu and Noto CJK
  font casks, and document the post-install PATH refresh;
- honor MAKE consistently in the dependency checker and build wrapper;
- prefer a compatible gmake before falling back to make;
- resolve GNU Make only for targets that invoke it;
- add a separate patch for tools/docs/sphinx-build-wrapper;
- split the English changes and zh_CN translations into separate patches;
  and
- document diskutil apfs addVolume diskX APFSX Linux in the English guide,
  its zh_CN translation, and the zh_CN contributor how-to.

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

Thanks,
Chen Miao

Chen Miao (5):
  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               |  55 ++++++-
 tools/docs/sphinx-pre-install                 | 154 +++++++++++++++++-
 5 files changed, 244 insertions(+), 10 deletions(-)


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

[PATCH v2 1/5] 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
actually 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 virtual environment requirements because Homebrew
does not provide a PyYAML formula. Document the macOS setup, the
--no-pdf option, and how to create a case-sensitive APFS volume before
cloning the kernel tree.

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

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..1b9d77ec3 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,7 +1565,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 v2 2/5] 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. 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      | 41 +++++++++++++++++++++++++++++-
 2 files changed, 43 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 1b9d77ec3..54f36c3b8 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,44 @@ 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 (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 check_make(self):
+        """Check for GNU Make 4.0 or newer."""
+        candidates = (
+            os.environ.get("MAKE"),
+            self.which("gmake"),
+            self.which("make"),
+        )
+
+        for make in candidates:
+            version = self.get_make_version(make)
+            if version and version >= MIN_MAKE_VERSION:
+                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 +1598,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 v2 3/5] 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. This keeps the
wrapper's selection consistent with sphinx-pre-install.

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

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 1bb962202..aa6a297db 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -71,6 +71,7 @@ from jobserver import JobserverExec         # pylint: disable=C0413,C0411,E0401
 #
 VENV_DEFAULT = "sphinx_latest"
 MIN_PYTHON_VERSION = PythonVersion("3.7").version
+MIN_MAKE_VERSION = PythonVersion("4.0").version
 PAPER = ["", "a4", "letter"]
 
 TARGETS = {
@@ -97,6 +98,46 @@ class SphinxBuilder:
     with the Kernel.
     """
 
+    @staticmethod
+    def get_make_version(cmd):
+        """Return the GNU Make version, or None for another make."""
+        if not cmd:
+            return None
+
+        try:
+            result = subprocess.run(
+                [cmd, "--version"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                check=True,
+            )
+        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 get_make(self):
+        """Select the first GNU Make 4.0 or newer in preference order."""
+        candidates = [
+            self.env.get("MAKE"),
+            shutil.which("gmake"),
+            shutil.which("make"),
+        ]
+
+        for cmd in candidates:
+            version = self.get_make_version(cmd)
+            if version and version >= MIN_MAKE_VERSION:
+                return cmd
+
+        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 +610,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 +829,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 v2 4/5] 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 v2 5/5] 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)

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

[Mauro Carvalho Chehab]

On Mon, 10 Aug 2026 22:33:05 +0800
Chen Miao <chenmiao.ku@gmail.com> 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 the command-line-only
> MacTeX cask without sudo. Only require Homebrew when dependencies
> actually 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 virtual environment requirements because Homebrew
> does not provide a PyYAML formula. Document the macOS setup, the
> --no-pdf option, and how to create a case-sensitive APFS volume before
> cloning the kernel tree.
> 
> Signed-off-by: Chen Miao <chenmiao.ku@gmail.com>
> ---
>  Documentation/doc-guide/sphinx.rst |  18 +++++
>  tools/docs/sphinx-pre-install      | 113 ++++++++++++++++++++++++++++-
>  2 files changed, 130 insertions(+), 1 deletion(-)
> 
> 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..1b9d77ec3 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,7 +1565,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")

This is not right: yaml is needed even outside venv/pip, as
it is required to build some docs - See Documentation/sphinx/parser_yaml.py
extension.

So, basically:

if python on macOS is *always* shipped with python3-yaml package (or
whatever name it has there), the code would be something like:

	# For whatever weird reason, macOS added a non-builtin module
	# on its python package, so no need to check as yaml is always
	# there.
	if sys.platform != "darwin":
		self.check_python_module("yaml")

Otherwise, this hunk is wrong.

>  
>          if self.pdf:
>              self.check_program("xelatex", DepManager.PDF_MANDATORY)



Thanks,
Mauro