Re: [PATCH bpf-next v1] bpf, docs: Reformat BPF maps page to be more readable

[Donald Hunter <donald.hunter@gmail.com>]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On Wed, Oct 12, 2022 at 04:27:15PM +0100, Donald Hunter wrote:
>> Add a more complete introduction, with links to man pages.
>> Move toctree of map types above usage notes.
>> Format usage notes to improve readability.
>> 
>> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
>> ---
>>  Documentation/bpf/maps.rst | 101 ++++++++++++++++++++++++-------------
>>  1 file changed, 65 insertions(+), 36 deletions(-)
>> 
>> diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst
>> index f41619e312ac..4906ff0f8382 100644
>> --- a/Documentation/bpf/maps.rst
>> +++ b/Documentation/bpf/maps.rst
>> @@ -1,52 +1,81 @@
>>  
>> -=========
>> -eBPF maps
>> +========
>> +BPF maps
>> +========
>> +
>> +BPF 'maps' provide generic storage of different types for sharing data between
>> +kernel and user space. There are several storage types available, including
>> +hash, array, bloom filter and radix-tree. Several of the map types exist to
>> +support specific BPF helpers that perform actions based on the map contents. The
>> +maps are accessed from BPF programs via BPF helpers which are documented in the
>> +`man-pages`_ for `bpf-helpers(7)`_.
>> +
>> +BPF maps are accessed from user space via the ``bpf`` syscall, which provides
>> +commands to create maps, lookup elements, update elements and delete
>> +elements. More details of the BPF syscall are available in
>> +:doc:`/userspace-api/ebpf/syscall` and in the `man-pages`_ for `bpf(2)`_.
>> <snipped>...
>> +.. Links:
>> +.. _man-pages: https://www.kernel.org/doc/man-pages/
>> +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
>> +.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
>
> I think you can just write "see :manpage:`bpf(2)`" without linking to
> external site.

I tried your suggestion but it just renders italicized text. I think it
is more helpful to provide a clickable link to the relevant man
page. Other documentation pages already provide clickable manpage links
and I followed existing practise from Documentation/bpf/syscall_api.rst

I would prefer to keep the clickable links.

> Otherwise LGTM.