Re: undefined label

[Markus Heiser <markus.heiser@darmarit.de>]

Am 07.03.19 um 10:17 schrieb Tobin C. Harding:
> Hi Jon,
> 
> I hit that undefined label warning again today.  Then just now I was
> sitting enjoying a quite scotch and the reason came to me.  It is caused
> by building part of the docs instead of the whole tree i.e. using
> 
> 	make SPHINXDIRS=admin-guide htmldocs
> 
> Gives the warning
> 
> 	WARNING: undefined label: numa (if the link has no caption the label must precede a section header)

The label 'numa' is not a part of the admin-guide (book), it is set in
the vm (book): Documentation/vm/numa.rst:1

If compiling only a book like admin-guide, those links are broken.  Its not only
'numa' which is broken and its not only the admin-guide which has cross-books
links in.

To close such cross-books links we can use intersphinx [1] and map to e.g.

   intersphinx_mapping = {
       'kernel': ('https://www.kernel.org/doc/html/latest/', None)}

If there is any interest in, I can implement a RFC for this.

-- Markus --

[1] https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

> 
> This is a hell of a gotcha, I wasted a bunch of cycles baffled as to why
> that label was not defined today :(  Super excited that I worked out why
> while day dreaming though.
> 
> Last time I sent in the 'fix' I must built with SPHINXDIRS, patched then
> built without SPHINXDIRS and thought the patch fixed it.
> 
> Anyways, hope you get a chuckle out of this.
> 
> All the best,
> Tobin.
>