Re: [PULL] Docs for 4.13

From: Linus Torvalds
Date: Tue Jul 04 2017 - 00:32:46 EST

On Mon, Jul 3, 2017 at 6:20 AM, Jonathan Corbet <corbet@xxxxxxx> wrote:
> You'll also encounter more than the usual number of conflicts, which
> is saying something.

Hmm. I fixed the ones that were actual data conflicts, but I think
there ends up being several things that are just stale or didn't get
updated by other pulls.

Eg things like

Error: Cannot open file ./kernel/rcu/srcu.c
Error: Cannot open file ./kernel/rcu/srcu.c

happen simply because that file no longer exists, and the docs never
got updated.

So my merge didn't even try to fix those kinds of things at all. I
literally just looked at the conflicts and moved those over to the rst
files, and that was it. There's a lot of other changes that never
cause conflicts for the simple reason that those changes never caused
documentation changes to begin with.

Now, this is obviously not new, but it does strike me that if checking
for these kinds of things was easier and part of "make allmodconfig",
then we might have less of it happen.

At the same time, lots of people run a lot of builds, and while I'd
love to see warnings about docs failures, I am *not* willing to slow
down my usual build enormously. I run "male allmodconfig" builds
between every single pull during the merge window, and while it's
often parallel with me looking at the problems, I don't really want to
slow the build down too much. And the doc building is still *slow*.

Is there some fast "just basic sanity checks" that would be more reasonable?

Because one thing that the switch to sphinx has done is that the doc
build environment seems saner (tool-wise). So now that kind of thing
would at least be _possible_ to do in ways I don't think was
reasonable with docbook.

And now docbook is finally gone. But sphinx isn't exactly a speed demon either.