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

[Chen Miao]

Weijie Yuan <wy@xxxxxxxxx> 于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@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.
>
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.