Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be

[Linus Torvalds <torvalds@linux-foundation.org>]

On Mon, Jun 27, 2022 at 8:34 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> >  (b) it requires some unusual build tools
> >
> > Now, (b) may some historical oddity, but at least if you have Fedora
> > installed and it still has sphinx version 2.2.11 or something like
> > that.
> >
> > And when you try to build docs, the makefile gives you some random pip
> > install thing that is entirely bogus.
>
> I'd be curious to know about how you got into that situation.  Fedora
> handles this stuff pretty readily.  I'll take another look at what we
> have there.

At some point I just did "dnf install sphinx", and it got me a sphinx install.

So then the kernel doc build system sees "oh, you need a newer version
of sphinx" or whatever, and suggests you do that horrible virtual
python sandbox thing and do a random pip install in that, which I
really don't want to do.

So I ignore it entirely, obviously.

End result: it took me a *loong* time to go "I wonder why modern
Fedora ships with an ancient version of sphinx, since the modern
version is apparently 4.x something".

And only at THAT point do you realize that there are three completely
different projects called "sphinx".

There's the docbuild one that comes from python, which is the sphinx I want.

There's the search engine 'sphinx', which is what is packaged as
"sphinx" in Fedora, and which the documentation code obviously refuses
to use.

There's also CMU sphinx, which is a voice recognition system.

End result: building the docs can be really confusing if you have the
wrong sphinx installed, and the "help message" is actually misleading
and very unhelpful.

              Linus