undefined label

undefined label

[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)

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.

Re: undefined label

[Markus Heiser]

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.
> 

Re: undefined label

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 10:58:07AM +0100, Markus Heiser wrote:
> 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.

Cool!  I think this would be super useful, I for one like using
SPHINXDIRS when developing docs incrementally so removing false warnings
would be nice.  I doubt I'm the only one to be baffled about Sphinx
references.  I'd be happy to review and test your RFC if you CC me.

thanks,
Tobin.

Re: undefined label

[Markus Heiser]

Hi Tobin,

Am 07.03.19 um 21:30 schrieb Tobin C. Harding:
> On Thu, Mar 07, 2019 at 10:58:07AM +0100, Markus Heiser wrote:
[...]
>> If there is any interest in, I can implement a RFC for this.
> 
> Cool!  I think this would be super useful, I for one like using
> SPHINXDIRS when developing docs incrementally so removing false warnings
> would be nice.  I doubt I'm the only one to be baffled about Sphinx
> references.  I'd be happy to review and test your RFC if you CC me.

Intersphinx has also drawbacks. E.g.:

 >> 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)}

This requires online access while building the output.  Anyway, as soon as
I have some time to spare I will send a RFC with more explanation about
(you will receive it in CC).

-- Markus --

> 
> thanks,
> Tobin.
> 

Re: undefined label

[Jani Nikula]

On Fri, 08 Mar 2019, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Hi Tobin,
>
> Am 07.03.19 um 21:30 schrieb Tobin C. Harding:
>> On Thu, Mar 07, 2019 at 10:58:07AM +0100, Markus Heiser wrote:
> [...]
>>> If there is any interest in, I can implement a RFC for this.
>> 
>> Cool!  I think this would be super useful, I for one like using
>> SPHINXDIRS when developing docs incrementally so removing false warnings
>> would be nice.  I doubt I'm the only one to be baffled about Sphinx
>> references.  I'd be happy to review and test your RFC if you CC me.
>
> Intersphinx has also drawbacks. E.g.:
>
>  >> 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)}
>
> This requires online access while building the output.  Anyway, as soon as
> I have some time to spare I will send a RFC with more explanation about
> (you will receive it in CC).

Please remember to call out the online access in the patch series. Such
a requirement is going to draw a lot of opposition.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: undefined label

[Jonathan Corbet]

On Fri, 08 Mar 2019 14:17:47 +0200
Jani Nikula <jani.nikula@linux.intel.com> wrote:

> >  >> 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)}  
> >
> > This requires online access while building the output.  Anyway, as soon as
> > I have some time to spare I will send a RFC with more explanation about
> > (you will receive it in CC).  
> 
> Please remember to call out the online access in the patch series. Such
> a requirement is going to draw a lot of opposition.

Indeed, I think that would a difficult requirement to add.  It may well be
better, in the end, to simply document this "feature" and live with it.

jon

Re: undefined label

[Jani Nikula]

On Mon, 11 Mar 2019, Jonathan Corbet <corbet@lwn.net> wrote:
> On Fri, 08 Mar 2019 14:17:47 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>
>> >  >> 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)}  
>> >
>> > This requires online access while building the output.  Anyway, as soon as
>> > I have some time to spare I will send a RFC with more explanation about
>> > (you will receive it in CC).  
>> 
>> Please remember to call out the online access in the patch series. Such
>> a requirement is going to draw a lot of opposition.
>
> Indeed, I think that would a difficult requirement to add.  It may well be
> better, in the end, to simply document this "feature" and live with it.

Apparently it's also possible to have a local intersphinx mapping file
which could be committed to git [1]. That obviously needs to be manually
updated occasionally, which is a bit tedious.

IIUC intersphinx also means that if a cross-reference target is not
present in the documentation being built, it'll use the canonical URL in
the intersphinx_mapping. So your locally built documentation for a
sub-book might contain links to kernel.org. I'm not sure whether that's
better or worse than broken links.

BR,
Jani.


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


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: undefined label

[Markus Heiser]

Am 11.03.19 um 18:30 schrieb Jonathan Corbet:
> On Fri, 08 Mar 2019 14:17:47 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
>>>   >> 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)}
>>>
>>> This requires online access while building the output.  Anyway, as soon as
>>> I have some time to spare I will send a RFC with more explanation about
>>> (you will receive it in CC).
>>
>> Please remember to call out the online access in the patch series. Such
>> a requirement is going to draw a lot of opposition.
> 
> Indeed, I think that would a difficult requirement to add.  It may well be
> better, in the end, to simply document this "feature" and live with it.
> 
> jon
> 

I know about this, thats why I mentioned this as a drawback.
May I find a soulution which uses intersphinx only when needed
(when using SPHINXDIRS).  Anyway it will be only a **RFC**.
But right now I don't have time anyway.  ;)

-- Markus --