On Mon, 11 Mar 2019, Jonathan Corbet <corbet@xxxxxxx> wrote:
> On Fri, 08 Mar 2019 14:17:47 +0200
> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> 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
