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)