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

[Jonathan Corbet <corbet@lwn.net>]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> On Sat, Jun 25, 2022 at 7:00 AM Jonathan Corbet <corbet@lwn.net> wrote:
>>
>> I said "some" - this was a proof-of-concept hack.  The complexity of
>> their symbol lookup code is ... daunting ... and not something that gets
>> fixed in one place.  More research is required...
>
> Note that at least for me, the issue with building docs isn't hugely
> performance related.

Those of us who do lots of docs builds see it a bit differently :)

> Yes, yes, it would be good if it was faster. But..
>
> The primary problems I see with building the docs (and thus checking
> them, the same way I do an allmodconfig build test) is
>
>  (a) it's insanely noisy, which makes and "check that it's ok" ENTIRELY USELESS.
>
> Seriously. There's a very solid reason why I require the standard
> kernel build to be entirely warning-free. Warnings are *BAD*. Even a
> single false-positive warning invalidates all other warnings.

I totally agree, which is why fixing warnings has been at the top of the
priority list for a long time.  That has mostly been done, with Mauro
having taken on the bulk of that work.

It is hard, though, to maintain the warning-free condition.  Warnings
are easy to add and most developers don't check.  Most documentation
changes don't go through the docs tree, so I can't enforce that kind of
check (and trying to force docs changes through my tree would be a cure
far worse than the disease).

Making the docs build faster might make it easier to insist that more
checking is done.

> And the doc build isn't about some "single warning" thing.
>
>  (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.

jon