docs: sphinx-pre-install: improve dependency checks
Subsystems (3)
v4 cover docs: sphinx-pre-install: improve dependency checks
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 v4:
- always pass LLVM=1 when invoking rustdoc, since Rust documentation requires LLVM even when the outer documentation build does not use it;
Thanks,
Chen Miao
Chen Miao (6):
docs: kdoc: add GNU Make detection
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 | 20 ++- tools/docs/sphinx-pre-install | 120 +++++++++++++++++- tools/lib/python/kdoc/gmake_detect.py | 62 +++++++++ 6 files changed, 238 insertions(+), 9 deletions(-) create mode 100644 tools/lib/python/kdoc/gmake_detect.py
base-commit: 8492d4e6bb7b9b1e78f2d17c4dda5272f25ec118
Signature · 1 line
2.50.1 (Apple Git-155)
PATCH v4 1/6 docs: kdoc: add GNU Make detection
The Sphinx dependency checker and build wrapper need to select a GNU Make executable that meets the minimum supported version. Keep the version parsing and command selection in a common module so both tools use identical behavior.
--- tools/lib/python/kdoc/gmake_detect.py | 62 +++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 tools/lib/python/kdoc/gmake_detect.py
tools/lib/python/kdoc/gmake_detect.py new file +62 -0
@@ -0,0 +1,62 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (c) 2026 Chen Miao <[email protected]> + +"""Detect a supported GNU Make executable.""" + +import re +import shutil +import subprocess +import sys + +from kdoc.python_version import PythonVersion + + +MIN_GMAKE_VERSION = PythonVersion("4.0").version + + +def get_gmake_version(cmd): + """Return the GNU Make version for *cmd*, or ``None`` otherwise.""" + if not cmd: + return None + + kwargs = {} + if sys.version_info < (3, 7): + kwargs["universal_newlines"] = True + else: + kwargs["text"] = True + + try: + result = subprocess.run( + [cmd, "--version"], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + check=True, + **kwargs, + ) + 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 find_gmake(make=None): + """Return the first GNU Make 4.0+ from MAKE, gmake, or make.""" + candidates = ( + make, + shutil.which("gmake"), + shutil.which("make"), + ) + + for cmd in candidates: + version = get_gmake_version(cmd) + if version and version >= MIN_GMAKE_VERSION: + return cmd + + return None
Signature · 1 line
2.50.1 (Apple Git-155)
PATCH v4 2/6 docs: sphinx-pre-install: add macOS Homebrew support
In reply to Chen MiaoThe 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 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 virtualenv requirements because Homebrew does not provide a PyYAML formula. Check the module even on macOS: it is required by the parser_yaml extension regardless of how Sphinx is installed. When it is missing, direct users to the default virtualenv mode.
--- Documentation/doc-guide/sphinx.rst | 18 +++++ tools/docs/sphinx-pre-install | 110 +++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+)
Documentation/doc-guide/sphinx.rst +18 -0
@@ -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 ---------------------------------
tools/docs/sphinx-pre-install +110 -0
134 lines not on this page · raw message
Signature · 1 line
2.50.1 (Apple Git-155)
PATCH v4 3/6 docs: sphinx-pre-install: check GNU Make version
In reply to Chen MiaoThe 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. Use the common kdoc detector so the dependency checker and build wrapper apply the same selection logic. Document the requirement and the macOS gmake invocation.
--- Documentation/doc-guide/sphinx.rst | 4 +++- tools/docs/sphinx-pre-install | 10 +++++++++- 2 files changed, 12 insertions(+), 2 deletions(-)
Documentation/doc-guide/sphinx.rst +3 -1
@@ -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 ---------------------------------
tools/docs/sphinx-pre-install +9 -1
@@ -37,6 +37,7 @@ import os.path src_dir = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(src_dir, '../lib/python')) from kdoc.python_version import PythonVersion +from kdoc.gmake_detect import find_gmake RECOMMENDED_VERSION = PythonVersion("3.4.3").version MIN_PYTHON_VERSION = PythonVersion("3.7").version
@@ -308,6 +309,13 @@ class MissingCheckers(AncillaryMethods): return None + def check_make(self): + """Check for GNU Make 4.0 or newer.""" + if find_gmake(os.environ.get("MAKE")): + 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 +1567,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)
Signature · 1 line
2.50.1 (Apple Git-155)
PATCH v4 4/6 docs: sphinx-build-wrapper: prefer gmake
In reply to Chen MiaoHomebrew 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. Use the common kdoc detector to keep this selection consistent with sphinx-pre-install.
--- tools/docs/sphinx-build-wrapper | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-)
tools/docs/sphinx-build-wrapper +13 -7
@@ -63,6 +63,7 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) from kdoc.python_version import PythonVersion +from kdoc.gmake_detect import find_gmake from kdoc.latex_fonts import LatexFontChecker from jobserver import JobserverExec # pylint: disable=C0413,C0411,E0401
@@ -97,6 +98,14 @@ class SphinxBuilder: with the Kernel. """ + def get_make(self): + """Select the first GNU Make 4.0 or newer in preference order.""" + make = find_gmake(self.env.get("MAKE")) + if make: + return make + + 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 +578,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 +797,8 @@ 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, "LLVM=1", "rustdoc"] if self.verbose: print(" ".join(cmd))
Signature · 1 line
2.50.1 (Apple Git-155)
PATCH v4 5/6 docs/zh_CN: doc-guide: document macOS Sphinx setup
In reply to Chen MiaoTranslate 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.
--- .../translations/zh_CN/doc-guide/sphinx.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)
Documentation/translations/zh_CN/doc-guide/sphinx.rst +16 -1
@@ -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> -
Signature · 1 line
2.50.1 (Apple Git-155)
Dongliang Mu
reviewerRe: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup
Quoted 24 lines · 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 <[email protected]>Acked-by Weijie Yuan <[email protected]>--- .../translations/zh_CN/doc-guide/sphinx.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)Documentation/translations/zh_CN/doc-guide/sphinx.rst +6
-0@@ -110,6 +110,22 @@ PDF和LaTeX构建 使用Sphinx的系统打包,而不是Python虚拟环境。 +macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写 +不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符, +将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷:: + + diskutil apfs addVolume diskX APFSX Linux +
Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 128
Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10
-0+在 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``。 +
Hi Chen Miao,
The zh_CN only keeps the translations, therefore, you should first put this part into the english documenation.
Of course, you can extend this patch into one with English and zh_CN changes.
Dongliang Mu
Quoted 8 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +0
-1Sphinx构建 ==========@@ -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> -
Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup
Quoted 37 lines · Dongliang Mu
Quoted 22 lines · 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 <[email protected]>Acked-by Weijie Yuan <[email protected]>--- .../translations/zh_CN/doc-guide/sphinx.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)Documentation/translations/zh_CN/doc-guide/sphinx.rst +6
-0@@ -110,6 +110,22 @@ PDF和LaTeX构建 使用Sphinx的系统打包,而不是Python虚拟环境。 +macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写 +不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符, +将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷:: + + diskutil apfs addVolume diskX APFSX Linux +Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126
Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10
-0+在 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``。 +Hi Chen Miao,
Quoted 5 lines
The
zh_CNonly keeps the translations, therefore, you should first put this part into the english documenation.Of course, you can extend this patch into one with English and
zh_CNchanges.
The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.
If so, let's add a 'Update xxx through...' in the commit message then.
But wait..:
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.
Thanks.
Dongliang Mu
reviewerRe: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup
Quoted 36 lines · Weijie Yuan
Quoted 35 lines · Dongliang Mu
Quoted 22 lines · 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 <[email protected]>Acked-by Weijie Yuan <[email protected]>--- .../translations/zh_CN/doc-guide/sphinx.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-)Documentation/translations/zh_CN/doc-guide/sphinx.rst +6
-0@@ -110,6 +110,22 @@ PDF和LaTeX构建 使用Sphinx的系统打包,而不是Python虚拟环境。 +macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写 +不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符, +将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷:: + + diskutil apfs addVolume diskX APFSX Linux +Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126
Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10
-0+在 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``。 +Hi Chen Miao,
Quoted 8 lines
Quoted 5 lines
The
zh_CNonly keeps the translations, therefore, you should first put this part into the english documenation.Of course, you can extend this patch into one with English and
zh_CNchanges.The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.
Oops, I missed this patch.
Yes, I mean, this patchset should only changes the English documentation. And then submit another patch to sync the zh_CN translation.
The changes to how-to.rst does not affect English documentation and I had commented with my reviewed-by tag.
Dongliang Mu
Quoted 2 lines
If so, let's add a 'Update xxx through...' in the commit message then.
Let us add another patch to keep the commit message and help us track translation status.
Quoted 9 lines
But wait..:
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.
I think Chen Miao might miss it unintentionally since this change is in another patch.
Quoted 2 lines
Thanks.
Re: [PATCH v4 5/6] docs/zh_CN: doc-guide: document macOS Sphinx setup
Quoted 33 lines · Dongliang Mu
Quoted 24 lines
Quoted 24 lines
Quoted 12 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +6
-0@@ -110,6 +110,22 @@ PDF和LaTeX构建 使用Sphinx的系统打包,而不是Python虚拟环境。 +macOS 默认使用不区分文件名大小写的 APFS 卷,而内核源码树中存在仅大小写 +不同的文件。克隆源码前,请用 ``diskutil apfs list`` 找到 APFS 容器标识符, +将下面的 ``diskX`` 替换为该标识符,并创建一个额外的大小写敏感卷:: + + diskutil apfs addVolume diskX APFSX Linux +Documentation/translations/zh_CN/doc-guide/sphinx.rst PDF和LaTeX构建 · line 126
Quoted 10 lines
Documentation/translations/zh_CN/doc-guide/sphinx.rst +10
-0+在 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``。 +Hi Chen Miao,
Quoted 8 lines
Quoted 5 lines
The
zh_CNonly keeps the translations, therefore, you should first put this part into the english documenation.Of course, you can extend this patch into one with English and
zh_CNchanges.The English Documentation for this is in [PATCH v4 2/6], so you mean it's better to wait until the English part is merged, then we can apply the Chinese translation part, I guess.
Quoted 7 lines
Oops, I missed this patch.
Yes, I mean, this patchset should only changes the English documentation. And then submit another patch to sync the
zh_CNtranslation.The changes to
how-to.rstdoes not affect English documentation and I had commented with my reviewed-by tag.
OK, thanks!
Quoted 11 lines
Quoted 8 lines
But wait..:
+该脚本还会检查 GNU Make 4.0 或更高版本;如果 Homebrew 将其安装为 +``gmake``,请使用 ``gmake htmldocs``,而不是 ``make htmldocs``。
Now I find that this part above is not in the original patch for English Docs, did you miss it on purpose? Sorry I didn't notice this in last rerolls.
I think Chen Miao might miss it unintentionally since this change is in another patch.
omg, I somehow missed the English original in [PATCH v4 3/6], too. Then it's my fault. Chen Miao merged two parts of changes for English Docs into one Chinese translation patch here. So he's right. I was just in a rush to send out the email and didn't take the time to double-check my question. Sorry for my recklessness.
Thanks!
PATCH v4 6/6 docs/zh_CN: how-to: document case-sensitive APFS setup
In reply to Chen MiaoThe 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.
--- Documentation/translations/zh_CN/how-to.rst | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/translations/zh_CN/how-to.rst +8 -0
@@ -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 虚拟环境,即只需要执行::
Signature · 1 line
2.50.1 (Apple Git-155)
Re: [PATCH v4 6/6] docs/zh_CN: how-to: document case-sensitive APFS setup
Quoted 7 lines · 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 <[email protected]>Acked-by Weijie Yuan <[email protected]>
BTW, this how-to file is only guidance for Chinese contributors. So there is no original English documentation and we don't need change the english documentation at the same time.
Dongliang Mu
Quoted 23 lines
--- Documentation/translations/zh_CN/how-to.rst | 8 ++++++++ 1 file changed, 8 insertions(+)Documentation/translations/zh_CN/how-to.rst +8
-0@@ -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 虚拟环境,即只需要执行::