On Tue, Feb 05, 2019 at 09:30:46AM +0100, Markus Heiser wrote:
> Am 05.02.19 um 00:03 schrieb Jonathan Corbet:
> > On Tue, 5 Feb 2019 08:12:20 +1100
> > "Tobin C. Harding" <[email protected]> wrote:
> >
> > > I tried to investigate this further and I am unable to reproduce the
> > > original warning. I'm using python virtual environment as directed by
> > > the output of `make htmldocs` so the environment should not have
> > > changed. The only other plausible explanation seems to be that I've
> > > gone mad and can't remember what I was doing three days ago.
> >
> > You are not the first to have reported such issues, though; I've seen a
> > couple of things go by in the past. Until we understand what is going on,
> > it's probably best to avoid hyphens in labels.
This statement is not sitting well with me Jon, we are using hyphens in
labels all over the place with *almost* no issue. Seems we either
change them all or none of them. (FTR I think we should not change any
of them.)
> Many errors are not reported again in rebuilds.
It's more than that. Seems that no .o files means dependencies are not
the same in docs directories to *usual* source code directories, as in
this example, a file with an outdated label was not rebuilt since it
wasn't touched.
Note to self, always do clean build for docs patches. Thanks.
> To reproduce this error run 'make cleandocs htmldocs' first. Then you will
> see
> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
>
> Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
> memory-allocation (if the link has no caption ...)
Can confirm I also get this warning, sloppy work by me I missed one
label. Second note to self, grep the whole tree not just /Documentation
Thanks for reporting this.
> In mm-api.rst you find this include:
>
> .. kernel-doc:: include/linux/slab.h
> :internal:
>
>
> And in slab.h you see a kmalloc DOC with a :ref:`..<memory-allocation>`
>
>
> /**
> * kmalloc - allocate memory
> * @size: how many bytes of memory are required.
> * @flags: the type of memory to allocate.
> *
> * kmalloc is the normal method of allocating memory
> * for objects smaller than page size in the kernel.
> *
> * The @flags argument may be one of the GFP flags defined at
> * include/linux/gfp.h and described at
> * :ref:`Documentation/core-api/mm-api.rst <mm-api-gfp-flags>`
> *
> * The recommended usage of the @flags is described at
> * :ref:`Documentation/core-api/memory-allocation.rst <memory-allocation>`
>
>
> With Tobin's patch applied to Jon's docs-next (cd7198fc959), this error comes
> up
> the first time (for me).
>
> Can we please revert cd7198fc959 / Thanks
I agree with you Markus, I'd like to see this reverted. Jon, your the
boss, if you want this patch to stay I can send in a patch to fix the
undefined label that this patch misses.
> @Tobin can you pleases test to revert cd7198fc959 and make a full build with
> 'cleandocs' first .. may this error comes up again for you and we can
> investigate any further .. if this depends to sphinx-Version or what ever.
With patch reverted, on docs-next, I've got 0 'undefined labels'
warnings.
Hope this adds more help than confusion :)
Tobin
