Re: [PULL] Docs for 4.13

[Daniel Vetter]

On Tue, Jul 04, 2017 at 01:24:13PM -0600, Jonathan Corbet wrote:
> On Mon, 3 Jul 2017 21:32:33 -0700
> Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx> wrote:
> 
> > 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.
> 
> I see Markus already tossed out a patch using the sphinx "dummy mode".
> It might be possible to create a dead-simple linter for this kind of
> thing that would be quite a bit faster, but I wonder how much we really
> need it.  Problems like this pop up with great regularity, but they
> tend to be caught and fixed fairly quickly.  Meanwhile, the world
> stubbornly refuses to end if the docs build tosses out a few (more)
> errors for a few days. I don't think we have to slow down everybody's
> build for this.
> 
> (Getting something into the build-and-boot testers might not be a bad
> idea, though).

0day runs make htmldocs on everything it can get its hand on. That was
about the first thing I've made sure happens when we went onto this docs
endeavor :-)

I guess 0day just isn't all that good at making sure people handle docs
issues in cross-tree conflicts, but hopefully that doesn't happen much in
the future anymore now that docbook is gone. The other problem is also
that the current htmldocs build is anything but clean (lots of warnings
about kernel-doc mismatching the function prototype, but lots others), and
we don't yet have anyone like Arnd trying to stem the tide ...

Wrt building: The big gain with sphinx is incremental builds: You can
finally edit a few comments/text, rebuild and a) not have to wait more
than a few seconds b) be sure it did rebuild everything that had to be
rebuild. Makes things much nicer for developers, not so much for
maintainers unfortunately, not sure how much faster we could make that.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch