Re: [PATCH 3/3] docs: Use underscore not hyphen in label

["Tobin C. Harding" <me@tobin.cc>]

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" <me@tobin.cc> 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