* undefined label
@ 2019-03-07 9:17 Tobin C. Harding
2019-03-07 9:58 ` Markus Heiser
0 siblings, 1 reply; 8+ messages in thread
From: Tobin C. Harding @ 2019-03-07 9:17 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-07 9:17 undefined label Tobin C. Harding
@ 2019-03-07 9:58 ` Markus Heiser
2019-03-07 20:30 ` Tobin C. Harding
0 siblings, 1 reply; 8+ messages in thread
From: Markus Heiser @ 2019-03-07 9:58 UTC (permalink / raw)
To: Tobin C. Harding, Jonathan Corbet; +Cc: linux-doc
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.
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-07 9:58 ` Markus Heiser
@ 2019-03-07 20:30 ` Tobin C. Harding
2019-03-08 8:56 ` Markus Heiser
0 siblings, 1 reply; 8+ messages in thread
From: Tobin C. Harding @ 2019-03-07 20:30 UTC (permalink / raw)
To: Markus Heiser; +Cc: Jonathan Corbet, linux-doc
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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-07 20:30 ` Tobin C. Harding
@ 2019-03-08 8:56 ` Markus Heiser
2019-03-08 12:17 ` Jani Nikula
0 siblings, 1 reply; 8+ messages in thread
From: Markus Heiser @ 2019-03-08 8:56 UTC (permalink / raw)
To: Tobin C. Harding; +Cc: Jonathan Corbet, linux-doc
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.
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-08 8:56 ` Markus Heiser
@ 2019-03-08 12:17 ` Jani Nikula
2019-03-11 17:30 ` Jonathan Corbet
0 siblings, 1 reply; 8+ messages in thread
From: Jani Nikula @ 2019-03-08 12:17 UTC (permalink / raw)
To: Markus Heiser, Tobin C. Harding; +Cc: Jonathan Corbet, linux-doc
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-08 12:17 ` Jani Nikula
@ 2019-03-11 17:30 ` Jonathan Corbet
2019-03-12 7:57 ` Jani Nikula
2019-03-12 8:19 ` Markus Heiser
0 siblings, 2 replies; 8+ messages in thread
From: Jonathan Corbet @ 2019-03-11 17:30 UTC (permalink / raw)
To: Jani Nikula; +Cc: Markus Heiser, Tobin C. Harding, linux-doc
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-11 17:30 ` Jonathan Corbet
@ 2019-03-12 7:57 ` Jani Nikula
2019-03-12 8:19 ` Markus Heiser
1 sibling, 0 replies; 8+ messages in thread
From: Jani Nikula @ 2019-03-12 7:57 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Markus Heiser, Tobin C. Harding, linux-doc
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: undefined label
2019-03-11 17:30 ` Jonathan Corbet
2019-03-12 7:57 ` Jani Nikula
@ 2019-03-12 8:19 ` Markus Heiser
1 sibling, 0 replies; 8+ messages in thread
From: Markus Heiser @ 2019-03-12 8:19 UTC (permalink / raw)
To: Jonathan Corbet, Jani Nikula; +Cc: Tobin C. Harding, linux-doc
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 --
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2019-03-12 8:19 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-03-07 9:17 undefined label Tobin C. Harding
2019-03-07 9:58 ` Markus Heiser
2019-03-07 20:30 ` Tobin C. Harding
2019-03-08 8:56 ` Markus Heiser
2019-03-08 12:17 ` Jani Nikula
2019-03-11 17:30 ` Jonathan Corbet
2019-03-12 7:57 ` Jani Nikula
2019-03-12 8:19 ` Markus Heiser
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.