Re: [PATCH bpf-next] bpf, doc: use internal linking for link to netdev FAQ

David Vernet
2023-03-13T03:10:01Z

On Mon, Mar 13, 2023 at 09:51:19AM +0700, Bagas Sanjaya wrote:
> Commit d56b0c461d19da ("bpf, docs: Fix link to netdev-FAQ target") fixes
> link to netdev FAQ documentation introduced in <blurb> introduced in
> 287f4fa99a5281 ("docs: Update references to netdev-FAQ"), although the
> former commit doesn't mention Fixes: to the latter. However, the former
> changes the link to external link to docs.kernel.org, in contrast to the
> internal linking employed by the latter.
>
> Use :doc: directive for linking to netdev FAQ doc, while keeping the
> anchor text intact and consistency with intention of 287f4fa99a5281.
>
> Fixes: d56b0c461d19da ("bpf, docs: Fix link to netdev-FAQ target")
> Fixes: 287f4fa99a5281 ("docs: Update references to netdev-FAQ")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

This regresses all of the warnings I fixed in d56b0c461d19da ("bpf,
docs: Fix link to netdev-FAQ target"):

[void@maniforge bpf-next]$ make -j SPHINXDIRS="bpf" htmldocs
make[2]: Nothing to be done for 'html'.
Using alabaster theme
source directory: bpf
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:125: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:150: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:207: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:232: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:398: WARNING: unknown document: '/process/maintainer-netdev'
/home/void/upstream/bpf-next/Documentation/bpf/bpf_devel_QA.rst:414: WARNING: unknown document: '/process/maintainer-netdev'

And it also causes the netdev-FAQ links to once again be broken and not
actually point to anything.

> ---
> Indeed, this internal linking fix should have been made against bpf
> tree, since the problematic original linking in 287f4fa99a5281 is also
> seen in bpf tree. If that is the case, I will rebase on that tree.
>
> Documentation/bpf/bpf_devel_QA.rst | 17 +++++++++--------
> 1 file changed, 9 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/bpf/bpf_devel_QA.rst b/Documentation/bpf/bpf_devel_QA.rst
> index 5f5f9ccc3862b4..e523991da9e0ce 100644
> --- a/Documentation/bpf/bpf_devel_QA.rst
> +++ b/Documentation/bpf/bpf_devel_QA.rst
> @@ -128,7 +128,7 @@ into the bpf-next tree will make their way into net-next tree. net and
> net-next are both run by David S. Miller. From there, they will go
> into the kernel mainline tree run by Linus Torvalds. To read up on the
> process of net and net-next being merged into the mainline tree, see
> -the `netdev-FAQ`_.
> +the :doc:`netdev-FAQ </process/maintainer-netdev>`.
>
>
>
> @@ -147,7 +147,8 @@ request)::
> Q: How do I indicate which tree (bpf vs. bpf-next) my patch should be applied to?
> ---------------------------------------------------------------------------------
>
> -A: The process is the very same as described in the `netdev-FAQ`_,
> +A: The process is the very same as described in the
> +:doc:`netdev-FAQ </process/maintainer-netdev>`,
> so please read up on it. The subject line must indicate whether the
> patch is a fix or rather "next-like" content in order to let the
> maintainers know whether it is targeted at bpf or bpf-next.
> @@ -206,8 +207,8 @@ ii) run extensive BPF test suite and
> Once the BPF pull request was accepted by David S. Miller, then
> the patches end up in net or net-next tree, respectively, and
> make their way from there further into mainline. Again, see the
> -`netdev-FAQ`_ for additional information e.g. on how often they are
> -merged to mainline.
> +:doc:`netdev-FAQ </process/maintainer-netdev>` for additional
> +information e.g. on how often they are merged to mainline.
>
> Q: How long do I need to wait for feedback on my BPF patches?
> -------------------------------------------------------------
> @@ -230,7 +231,8 @@ Q: Are patches applied to bpf-next when the merge window is open?
> -----------------------------------------------------------------
> A: For the time when the merge window is open, bpf-next will not be
> processed. This is roughly analogous to net-next patch processing,
> -so feel free to read up on the `netdev-FAQ`_ about further details.
> +so feel free to read up on the
> +:doc:`netdev-FAQ </process/maintainer-netdev>` about further details.
>
> During those two weeks of merge window, we might ask you to resend
> your patch series once bpf-next is open again. Once Linus released
> @@ -394,7 +396,7 @@ netdev kernel mailing list in Cc and ask for the fix to be queued up:
> netdev@vger.kernel.org
>
> The process in general is the same as on netdev itself, see also the
> -`netdev-FAQ`_.
> +:doc:`netdev-FAQ </process/maintainer-netdev>`.
>
> Q: Do you also backport to kernels not currently maintained as stable?
> ----------------------------------------------------------------------
> @@ -410,7 +412,7 @@ Q: The BPF patch I am about to submit needs to go to stable as well
> What should I do?
>
> A: The same rules apply as with netdev patch submissions in general, see
> -the `netdev-FAQ`_.
> +the :doc:`netdev-FAQ </process/maintainer-netdev>`.
>
> Never add "``Cc: stable@vger.kernel.org``" to the patch description, but
> ask the BPF maintainers to queue the patches instead. This can be done
> @@ -685,7 +687,6 @@ when:
>
> .. Links
> .. _Documentation/process/: https://www.kernel.org/doc/html/latest/process/
> -.. _netdev-FAQ: https://www.kernel.org/doc/html/latest/process/maintainer-netdev.html
> .. _selftests:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/
> .. _Documentation/dev-tools/kselftest.rst:
>
> base-commit: 49b5300f1f8f2b542b31d63043c2febd13edbe3a
> --
> An old man doll... just what I always wanted! - Clara
>