[PATCH v3 0/6] 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 v3:

- restore the PyYAML availability check on macOS, as the parser_yaml
  extension requires it regardless of how Sphinx is installed; and
- move GNU Make version parsing and command selection to the shared
  tools/lib/python/kdoc/gmake_detect.py module, used by both the dependency
  checker and Sphinx build wrapper.

Link: https://lore.kernel.org/linux-doc/20260810143311.57775-1-chenmiao.ku@xxxxxxxxx/

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               |  23 +++-
 tools/docs/sphinx-pre-install                 | 120 +++++++++++++++++-
 tools/lib/python/kdoc/gmake_detect.py         |  62 +++++++++
 6 files changed, 241 insertions(+), 9 deletions(-)
 create mode 100644 tools/lib/python/kdoc/gmake_detect.py


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