broken link in bpf/bpf_devel_QA

broken link in bpf/bpf_devel_QA

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

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

Re: broken link in bpf/bpf_devel_QA

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1791 bytes --]

On Fri, Feb 17, 2023 at 10:10:12AM -0700, Ross Zwisler wrote:
> 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:
> 
>  `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.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH] Documentation: bpf: Fix link to BTF doc

[Bagas Sanjaya]

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/Y++09LKx25dtR4Ow@google.com/
Fixes: 6736aa793c2b5f ("selftests/bpf: Add general instructions for test execution")
Reported-by: Ross Zwisler <zwisler@google.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/bpf/bpf_devel_QA.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst
index 03d4993eda6f05..a4c1634d18955d 100644
--- a/Documentation/bpf/bpf_devel_QA.rst
+++ b/Documentation/bpf/bpf_devel_QA.rst
@@ -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
-- 
An old man doll... just what I always wanted! - Clara

Re: broken link in bpf/bpf_devel_QA

[Ross Zwisler]

On Sun, Feb 19, 2023 at 10:02:33AM +0700, Bagas Sanjaya wrote:
> On Fri, Feb 17, 2023 at 10:10:12AM -0700, Ross Zwisler wrote:
> > 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:
> > 
> >  `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.

Thanks for the quick fix!