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@xxxxxxxxx/

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