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

[Weijie Yuan <wy@wyuan.org>]

On Sun, Aug 09, 2026 at 09:21:45PM +0800, Dongliang Mu wrote:
> 
> On 8/9/26 9:02 PM, Weijie Yuan wrote:
> > 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@gmail.com>
> > > ---
> > >   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 ;-)
> 
> For Mac OSX, you need to first establish a Case-sensitive APFS Volume, and
> in this volume you can execute thse commands.

Yes. So what I mean is: for documentation that tries to keep the barrier
to entry for new contributors as low as possible, if we are going to
introduce macOS-specific instructions here, would it be worth mentioning
this as well (i.e. the case-sensitivity issue)?

That said, if someone is already doing this kind of work, they probably
do not need much explanation about it anyway.

> > 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.)
> 
> I don't prefer to add many description about "how to start kernel
> development on Mac OS X". Some key parts should be enough.

Yes. Agreed.

> > 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)
> 
> This is a good suggestion. However, many minor changes of documentation
> contains EN and zh_CN in the same patch :(

Then I guess we'll just have to wait for the next patch adding a new
translation to verify the statistics produced by the script.

Thanks.