Date:   Mon, 13 Mar 2023 07:36:02 -0500
From:   David Vernet <void@manifault.com>
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     Linux BPF <bpf@vger.kernel.org>,
        Linux Documentation <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Alexei Starovoitov <ast@kernel.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Andrii Nakryiko <andrii@kernel.org>,
        Martin KaFai Lau <martin.lau@linux.dev>,
        Song Liu <song@kernel.org>, Yonghong Song <yhs@fb.com>,
        John Fastabend <john.fastabend@gmail.com>,
        KP Singh <kpsingh@kernel.org>,
        Stanislav Fomichev <sdf@google.com>,
        Hao Luo <haoluo@google.com>, Jiri Olsa <jolsa@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        "David S. Miller" <davem@davemloft.net>,
        "Tobin C. Harding" <me@tobin.cc>
Subject: Re: [PATCH bpf-next] bpf, doc: use internal linking for link to
 netdev FAQ
Message-ID: <20230313123602.GA2392@maniforge>
References: <20230313025119.17430-1-bagasdotme@gmail.com>
 <20230313030938.GA152792@maniforge>
 <ZA6knaEQcddfTCyS@debian.me>
 <fefa25fe-8148-cbd7-a91e-e4713eb6b0ef@gmail.com>
 <4653cfd1-7209-6e49-4f01-fcc3f82f16ce@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <4653cfd1-7209-6e49-4f01-fcc3f82f16ce@gmail.com>
User-Agent: Mutt/2.2.9 (2022-11-12)
Precedence: bulk

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