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@xxxxxxxxx>
> ---
>  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.