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

[Chen Miao]

Weijie Yuan <wy@xxxxxxxxx> 于2026年8月9日周日 22:12写道：
>
> 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@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 ;-)
> >
> > 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.
>
Thanks for the clarification. I'll first check whether the kernel documentation
already has something like a "macOS kernel development guide." If not, I think
it might be worth documenting this.

In particular, macOS uses a case-insensitive APFS volume by default, which can
cause unexpected problems for newcomers working with the Linux kernel source
tree. It would be unfortunate if there were no documentation covering the
things developers need to be aware of when doing kernel development on macOS.
That said, I suspect this would be better handled in a separate patch series.

Of course, if such documentation already exists, then that's even better, and
there would be no need to add another one.

My main concern is that, if there are currently no macOS-specific notes in the
kernel documentation, some important details may remain implicit knowledge
among experienced macOS users rather than being documented for newcomers.

Thanks,
Chen Miao
>
> > > 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.