Re: undefined label

[Jani Nikula <jani.nikula@linux.intel.com>]

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