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

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

[Bagas Sanjaya]

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

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

[David Vernet]

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
> 

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

[Bagas Sanjaya]

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

On Sun, Mar 12, 2023 at 10:09:38PM -0500, David Vernet wrote:
> 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.

Hi,

I don't see these warnings in my builds. I'm using Sphinx 2.4.4
(virtualenv, install with pip3 install -r
Documentation/sphinx/requirements.txt). I guess your Sphinx version
doesn't support :doc: directive.

Also, did you enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS,
and CONFIG_WARN_ABI_ERRORS?

Thanks.

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

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

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

[Bagas Sanjaya]

On 3/13/23 11:20, Bagas Sanjaya wrote:
> On Sun, Mar 12, 2023 at 10:09:38PM -0500, David Vernet wrote:
>> 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.
> 
> Hi,
> 
> I don't see these warnings in my builds. I'm using Sphinx 2.4.4
> (virtualenv, install with pip3 install -r
> Documentation/sphinx/requirements.txt). I guess your Sphinx version
> doesn't support :doc: directive.
> 
> Also, did you enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS,
> and CONFIG_WARN_ABI_ERRORS?
> 
> Thanks.
> 

Oops, I didn't see the context.

When I rebuild the docs, I always omit SPHINXDIRS as you mentioned.
For :doc: links to work, you need to just do ``make htmldocs`` and
DO NOT specify that variable.

Anyway, these warnings make sense since the target is absolute
(rather than relative).

Thanks.

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

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

[Bagas Sanjaya]

On 3/13/23 11:42, Bagas Sanjaya wrote:
> On 3/13/23 11:20, Bagas Sanjaya wrote:
>> On Sun, Mar 12, 2023 at 10:09:38PM -0500, David Vernet wrote:
>>> 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.
>>
>> Hi,
>>
>> I don't see these warnings in my builds. I'm using Sphinx 2.4.4
>> (virtualenv, install with pip3 install -r
>> Documentation/sphinx/requirements.txt). I guess your Sphinx version
>> doesn't support :doc: directive.
>>
>> Also, did you enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS,
>> and CONFIG_WARN_ABI_ERRORS?
>>
>> Thanks.
>>
> 
> Oops, I didn't see the context.
> 
> When I rebuild the docs, I always omit SPHINXDIRS as you mentioned.
> For :doc: links to work, you need to just do ``make htmldocs`` and
> DO NOT specify that variable.
> 
> Anyway, these warnings make sense since the target is absolute
> (rather than relative).
> 

Hi again,

I think SPHINXDIRS specifies the subdir as root directory when
resolving references, so when there are references to docs
outside SPHINXDIRS, nonexistent doc warnings will occur. For normal
(full) htmldocs builds though, these will go away (see [1]).

Thanks.

[1]: https://lore.kernel.org/all/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.com/

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

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

[David Vernet]

On Mon, Mar 13, 2023 at 02:57:59PM +0700, Bagas Sanjaya wrote:
> On 3/13/23 11:42, Bagas Sanjaya wrote:
> > On 3/13/23 11:20, Bagas Sanjaya wrote:
> >> On Sun, Mar 12, 2023 at 10:09:38PM -0500, David Vernet wrote:
> >>> 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.
> >>
> >> Hi,
> >>
> >> I don't see these warnings in my builds. I'm using Sphinx 2.4.4
> >> (virtualenv, install with pip3 install -r
> >> Documentation/sphinx/requirements.txt). I guess your Sphinx version
> >> doesn't support :doc: directive.
> >>
> >> Also, did you enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS,
> >> and CONFIG_WARN_ABI_ERRORS?
> >>
> >> Thanks.
> >>
> > 
> > Oops, I didn't see the context.
> > 
> > When I rebuild the docs, I always omit SPHINXDIRS as you mentioned.
> > For :doc: links to work, you need to just do ``make htmldocs`` and
> > DO NOT specify that variable.

Hi Bagas,

Sure, but there are practicalities to consider here. It takes O(minutes)
to do a full docs build, as opposed to O(seconds). I've done reviews of
docs patches where the engineer tried to build the docs tree, but
thought it was hung and ended up cancelling it. Full docs builds also
unfortunately spew quite a few warnings in other subtrees. You have to
carefully wade through the warnings in those other subtrees to ensure
you haven't added any new ones.

It's hard enough to get people to write documentation. It's also hard
enough to get them to test building their documentation before
submitting it. I think there is a lot of value in being able to build
the documentation for the subtree you're contributing to, and be able to
have some expectation that it builds cleanly. Let's not make it more
difficult for the people who are actually adding substantive
documentation.

> > 
> > Anyway, these warnings make sense since the target is absolute
> > (rather than relative).
> > 
> 
> Hi again,
> 
> I think SPHINXDIRS specifies the subdir as root directory when
> resolving references, so when there are references to docs
> outside SPHINXDIRS, nonexistent doc warnings will occur. For normal
> (full) htmldocs builds though, these will go away (see [1]).
> 
> Thanks.
> 
> [1]: https://lore.kernel.org/all/f4d40da6-756b-9e75-b867-cc9eedc4b232@gmail.com/

Thanks, I understand that, but I'm not seeing why it's necessary to use
:doc: or :ref: to point to pages in other subtrees. Most people are
already going to docs.kernel.org anyways, and it's easy to map a URL
there to an internal page in the docs tree if you need to. I'm more than
happy to be corrected here, but as I said above, I'm trying to optimize
for the people who are adding substantive documentation to BPF.

Thanks,
David

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

[Jonathan Corbet]

David Vernet <void@manifault.com> writes:

> Sure, but there are practicalities to consider here. It takes O(minutes)
> to do a full docs build, as opposed to O(seconds). I've done reviews of
> docs patches where the engineer tried to build the docs tree, but
> thought it was hung and ended up cancelling it. Full docs builds also
> unfortunately spew quite a few warnings in other subtrees. You have to
> carefully wade through the warnings in those other subtrees to ensure
> you haven't added any new ones.
>
> It's hard enough to get people to write documentation. It's also hard
> enough to get them to test building their documentation before
> submitting it. I think there is a lot of value in being able to build
> the documentation for the subtree you're contributing to, and be able to
> have some expectation that it builds cleanly. Let's not make it more
> difficult for the people who are actually adding substantive
> documentation.

I get your point, but that is essentially saying that there should be no
linkages between our documentation subtrees, which defeats much of the
purpose of using a system like Sphinx.

In this specific case, though, there is a better solution.  Text like:

  see the netdev FAQ (Documentation/process/maintainer-netdev.rst)

will add links in the built docs, and also tells readers of the
plain-text files where they should be looking.  Without adding warnings.

For the bigger problem, the right answer is to start using intersphinx.
I guess I need to get serious about playing with that.

Thanks,

jon

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

[David Vernet]

On Mon, Mar 13, 2023 at 07:37:25AM -0600, Jonathan Corbet wrote:
> David Vernet <void@manifault.com> writes:
> 
> > Sure, but there are practicalities to consider here. It takes O(minutes)
> > to do a full docs build, as opposed to O(seconds). I've done reviews of
> > docs patches where the engineer tried to build the docs tree, but
> > thought it was hung and ended up cancelling it. Full docs builds also
> > unfortunately spew quite a few warnings in other subtrees. You have to
> > carefully wade through the warnings in those other subtrees to ensure
> > you haven't added any new ones.
> >
> > It's hard enough to get people to write documentation. It's also hard
> > enough to get them to test building their documentation before
> > submitting it. I think there is a lot of value in being able to build
> > the documentation for the subtree you're contributing to, and be able to
> > have some expectation that it builds cleanly. Let's not make it more
> > difficult for the people who are actually adding substantive
> > documentation.
> 
> I get your point, but that is essentially saying that there should be no
> linkages between our documentation subtrees, which defeats much of the
> purpose of using a system like Sphinx.

I certainly agree that inter-subtree links are great to have, though in
my opinion, other features such as linking kernel-doc comments, auto
section labeling, etc make Sphinx very useful in their own right. But
yes, having inter-subtree links is of course a useful feature as well.

> In this specific case, though, there is a better solution.  Text like:
> 
>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
> 
> will add links in the built docs, and also tells readers of the
> plain-text files where they should be looking.  Without adding warnings.

Nice, seems like the best of both worlds. A syntax clarification
question: are you saying that this would work?

> see the `netdev-FAQ`_.
>
>   <snip>
>
> .. _netdev-FAQ: Documentation/process/maintainer-netdev.rst

Or is it required to have the full path inline in the text, as in your
example:

>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)

The benefit of the former is of course that you only have to specify the
link in one place.

> For the bigger problem, the right answer is to start using intersphinx.
> I guess I need to get serious about playing with that.

Based on a quick online search, that indeed sounds like the ideal
solution.

Thanks,
David

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

[Jonathan Corbet]

David Vernet <void@manifault.com> writes:

>> In this specific case, though, there is a better solution.  Text like:
>> 
>>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
>> 
>> will add links in the built docs, and also tells readers of the
>> plain-text files where they should be looking.  Without adding warnings.
>
> Nice, seems like the best of both worlds. A syntax clarification
> question: are you saying that this would work?
>
>> see the `netdev-FAQ`_.
>>
>>   <snip>
>>
>> .. _netdev-FAQ: Documentation/process/maintainer-netdev.rst
>
> Or is it required to have the full path inline in the text, as in your
> example:
>
>>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
>
> The benefit of the former is of course that you only have to specify the
> link in one place.

Yeah, but the latter is what we actually have.

Thanks,

jon

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

[David Vernet]

On Mon, Mar 13, 2023 at 08:27:11AM -0600, Jonathan Corbet wrote:
> David Vernet <void@manifault.com> writes:
> 
> >> In this specific case, though, there is a better solution.  Text like:
> >> 
> >>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
> >> 
> >> will add links in the built docs, and also tells readers of the
> >> plain-text files where they should be looking.  Without adding warnings.
> >
> > Nice, seems like the best of both worlds. A syntax clarification
> > question: are you saying that this would work?
> >
> >> see the `netdev-FAQ`_.
> >>
> >>   <snip>
> >>
> >> .. _netdev-FAQ: Documentation/process/maintainer-netdev.rst
> >
> > Or is it required to have the full path inline in the text, as in your
> > example:
> >
> >>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
> >
> > The benefit of the former is of course that you only have to specify the
> > link in one place.
> 
> Yeah, but the latter is what we actually have.

Ack, just wanted to make sure I understood the suggestion. I think this
is just fine. There's really no need to add 5 - 6 links in the same file
anyways.

Bagas would you be OK with submitting a v2 patch which changes the first
instance of the `netdev-FAQ`_ to netdev FAQ
(Documentation/process/maintainer-netdev.rst) per Jon's suggestion?

Thanks,
David

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

[Bagas Sanjaya]

On 3/13/23 20:37, Jonathan Corbet wrote:
> David Vernet <void@manifault.com> writes:
> 
>> Sure, but there are practicalities to consider here. It takes O(minutes)
>> to do a full docs build, as opposed to O(seconds). I've done reviews of
>> docs patches where the engineer tried to build the docs tree, but
>> thought it was hung and ended up cancelling it. Full docs builds also
>> unfortunately spew quite a few warnings in other subtrees. You have to
>> carefully wade through the warnings in those other subtrees to ensure
>> you haven't added any new ones.
>>

I have tried to add CONFIG_COMPILE_TEST + CONFIG_WARN_MISSING_DOCUMENTS
+ CONFIG_WARN_ABI_ERRORS when performing htmldocs build, but hangs on
checking missing documents (even I noticed this behavior when cleandocs).

> I get your point, but that is essentially saying that there should be no
> linkages between our documentation subtrees, which defeats much of the
> purpose of using a system like Sphinx.
> 

I mean external referencing to docs.kernel.org when simple internal linking
below should suffice, right?

> In this specific case, though, there is a better solution.  Text like:
> 
>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
> 
> will add links in the built docs, and also tells readers of the
> plain-text files where they should be looking.  Without adding warnings.
> 

OK.

In 287f4fa99a5281, Sphinx generates netdev-FAQ crossref as link to
`/process/maintainer-netdev.html#netdev-faq`, due to use of external
link syntax.

Thanks.

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

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

[Bagas Sanjaya]

On 3/13/23 21:32, David Vernet wrote:
> On Mon, Mar 13, 2023 at 08:27:11AM -0600, Jonathan Corbet wrote:
>> David Vernet <void@manifault.com> writes:
>>
>>>> In this specific case, though, there is a better solution.  Text like:
>>>>
>>>>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
>>>>
>>>> will add links in the built docs, and also tells readers of the
>>>> plain-text files where they should be looking.  Without adding warnings.
>>>
>>> Nice, seems like the best of both worlds. A syntax clarification
>>> question: are you saying that this would work?
>>>
>>>> see the `netdev-FAQ`_.
>>>>
>>>>   <snip>
>>>>
>>>> .. _netdev-FAQ: Documentation/process/maintainer-netdev.rst
>>>
>>> Or is it required to have the full path inline in the text, as in your
>>> example:
>>>
>>>>   see the netdev FAQ (Documentation/process/maintainer-netdev.rst)
>>>
>>> The benefit of the former is of course that you only have to specify the
>>> link in one place.
>>
>> Yeah, but the latter is what we actually have.
> 
> Ack, just wanted to make sure I understood the suggestion. I think this
> is just fine. There's really no need to add 5 - 6 links in the same file
> anyways.
> 
> Bagas would you be OK with submitting a v2 patch which changes the first
> instance of the `netdev-FAQ`_ to netdev FAQ
> (Documentation/process/maintainer-netdev.rst) per Jon's suggestion?
> 

The target is actually netdev subsytem documentation, however, so I need
to change the wording surrounding the link.

Thanks!

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