Skip to contentSkip to conversation

broken link in bpf/bpf_devel_QA

PATCH Superseded Ross Zwisler 2 participants 4 messages Feb 17, 2023 – Feb 21, 2023

Subsystems (2)
Documentation BPF

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Ross Zwisler

author
#0 lore raw

Hi,

I was checking out this page:

https://docs.kernel.org/bpf/bpf_devel_QA.html

and noticed that we have two links to .rst pages that are getting converted to links in different ways. This one:

See the kernels selftest Documentation/dev-tools/kselftest.rst_ document for further documentation.

is getting converted to a full external link:

<p>See the kernels selftest <a class="reference external" href="https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html">Documentation/dev-tools/kselftest.rst</a> document for further documentation.</p>

While this one:

Finally to ensure support for latest BPF Type Format features - discussed in Documentation/bpf/btf.rst_

Is left as a short local link to a nonexistent .rst page:

<p>Finally to ensure support for latest BPF Type Format features - discussed in <a class="reference external" href="btf.rst">Documentation/bpf/btf.rst</a>

I think this could point to either of these locations and be okay:

https://www.kernel.org/doc/html/latest/bpf/btf.html
https://docs.kernel.org/bpf/btf.html

but, as it is it's showing up as a broken link.

Given that the page source for these two links are basically the same:

Documentation/dev-tools/kselftest.rst
and
Documentation/bpf/btf.rst

I'm guessing this is an issue with how Sphinx is generating the resulting html, probably because it's trying to generate a more 'local' sort link for the btf.rst page?

Thanks,
- Ross

#1 lore raw
Quoted 33 lines · Ross Zwisler

Hi,

I was checking out this page:

https://docs.kernel.org/bpf/bpf_devel_QA.html

and noticed that we have two links to .rst pages that are getting converted to links in different ways. This one:

See the kernels selftest Documentation/dev-tools/kselftest.rst_ document for further documentation.

is getting converted to a full external link:

<p>See the kernels selftest <a class="reference external" href="https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html">Documentation/dev-tools/kselftest.rst</a> document for further documentation.</p>

While this one:

Finally to ensure support for latest BPF Type Format features - discussed in Documentation/bpf/btf.rst_

Is left as a short local link to a nonexistent .rst page:

<p>Finally to ensure support for latest BPF Type Format features - discussed in <a class="reference external" href="btf.rst">Documentation/bpf/btf.rst</a>

<snipped>...

Given that the page source for these two links are basically the same:

Quoted 7 lines

Documentation/dev-tools/kselftest.rst
and
Documentation/bpf/btf.rst

I'm guessing this is an issue with how Sphinx is generating the resulting html, probably because it's trying to generate a more 'local' sort link for the btf.rst page?

I see that the issue is due to link handling when the external link target is actually internal link sibling (i.e. the same level as doc where the target is link from).

The fix is to simply use internal link mechanism. I will send the patch as reply to this message shortly.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

PATCH 1/1 Documentation: bpf: Fix link to BTF doc

Ross reported broken link to BTF documentation (Documentation/bpf/btf.rst) in Documentation/bpf/bpf_devel_QA.rst. The link in question is written using external link syntax, which behaves badly when the link target is sibling doc.

Fix the link by replacing external link syntax with simply writing out the target doc.

Link https://lore.kernel.org/linux-doc/[email protected]/ open here
Fixes 6736aa793c2b5f ("selftests/bpf: Add general instructions for test execution")
Reported-by Ross Zwisler <[email protected]>
Signed-off-by Bagas Sanjaya <[email protected]>
---
 Documentation/bpf/bpf_devel_QA.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/bpf/bpf_devel_QA.rst +1 -1
index 03d4993eda6f05..a4c1634d18955d 100644
@@ -469,7 +469,7 @@ under test should match the config file fragment in
 tools/testing/selftests/bpf as closely as possible.
 
 Finally to ensure support for latest BPF Type Format features -
-discussed in `Documentation/bpf/btf.rst`_ - pahole version 1.16
+discussed in Documentation/bpf/btf.rst - pahole version 1.16
 is required for kernels built with CONFIG_DEBUG_INFO_BTF=y.
 pahole is delivered in the dwarves package or can be built
 from source at

base-commit: 168de0233586fb06c5c5c56304aa9a928a09b0ba

Signature · 1 line
An old man doll... just what I always wanted! - Clara
author
#3 lore raw
In reply to Bagas Sanjaya
Quoted 42 lines · Bagas Sanjaya
Quoted 33 lines · Ross Zwisler

Hi,

I was checking out this page:

https://docs.kernel.org/bpf/bpf_devel_QA.html

and noticed that we have two links to .rst pages that are getting converted to links in different ways. This one:

See the kernels selftest Documentation/dev-tools/kselftest.rst_ document for further documentation.

is getting converted to a full external link:

<p>See the kernels selftest <a class="reference external" href="https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html">Documentation/dev-tools/kselftest.rst</a> document for further documentation.</p>

While this one:

Finally to ensure support for latest BPF Type Format features - discussed in Documentation/bpf/btf.rst_

Is left as a short local link to a nonexistent .rst page:

<p>Finally to ensure support for latest BPF Type Format features - discussed in <a class="reference external" href="btf.rst">Documentation/bpf/btf.rst</a>

<snipped>...

Given that the page source for these two links are basically the same:

Quoted 7 lines

Documentation/dev-tools/kselftest.rst
and
Documentation/bpf/btf.rst

I'm guessing this is an issue with how Sphinx is generating the resulting html, probably because it's trying to generate a more 'local' sort link for the btf.rst page?

Quoted 8 lines

I see that the issue is due to link handling when the external link target is actually internal link sibling (i.e. the same level as doc where the target is link from).

The fix is to simply use internal link mechanism. I will send the patch as reply to this message shortly.

Thanks.

Thanks for the quick fix!