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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <4653cfd1-7209-6e49-4f01-fcc3f82f16ce@gmail.com>
Date:   Mon, 13 Mar 2023 14:57:59 +0700
From:   Bagas Sanjaya <bagasdotme@...il.com>
To:     David Vernet <void@...ifault.com>
Cc:     Linux BPF <bpf@...r.kernel.org>,
        Linux Documentation <linux-doc@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        Alexei Starovoitov <ast@...nel.org>,
        Daniel Borkmann <daniel@...earbox.net>,
        Andrii Nakryiko <andrii@...nel.org>,
        Martin KaFai Lau <martin.lau@...ux.dev>,
        Song Liu <song@...nel.org>, Yonghong Song <yhs@...com>,
        John Fastabend <john.fastabend@...il.com>,
        KP Singh <kpsingh@...nel.org>,
        Stanislav Fomichev <sdf@...gle.com>,
        Hao Luo <haoluo@...gle.com>, Jiri Olsa <jolsa@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>,
        "Tobin C. Harding" <me@...in.cc>
Subject: Re: [PATCH bpf-next] bpf, doc: use internal linking for link to
 netdev FAQ

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@...iforge 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