Message-ID: <4653cfd1-7209-6e49-4f01-fcc3f82f16ce@gmail.com>
Date:   Mon, 13 Mar 2023 14:57:59 +0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.8.0
Subject: Re: [PATCH bpf-next] bpf, doc: use internal linking for link to
 netdev FAQ
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     David Vernet <void@manifault.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>
References: <20230313025119.17430-1-bagasdotme@gmail.com>
 <20230313030938.GA152792@maniforge> <ZA6knaEQcddfTCyS@debian.me>
 <fefa25fe-8148-cbd7-a91e-e4713eb6b0ef@gmail.com>
Content-Language: en-US
In-Reply-To: <fefa25fe-8148-cbd7-a91e-e4713eb6b0ef@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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