[PATCH bpf-next 0/3] Fix Navigation Issues in Docs

[PATCH bpf-next 0/3] Fix Navigation Issues in Docs

[Dave Tucker]

This patch set fixes a couple of documentation issues that was causing
some strange behaviour when the sidebar was rendered in the HTML docs.

1. The underlines in the BTF document weren't following the docs
guidelines, which I believe caused an issue rendering the TOC with my
other patches applied
2. Mixing the Sphix toctree with named sections was causing name stutter
in the sidebar navigation. For example:

  | BPF Type Format
    | - BPF Type Format
3. The libbpf API documentation wasn't referenced in a toctree

It also renames bpf_lsm.rst to prog_lsm.rst such that documentation for
program types can be included in the toctree via glob for prog_*

Dave Tucker (3):
  docs: change underline in btf to match style guide
  docs: Rename bpf_lsm.rst to prog_lsm.rst
  docs: fix ordering of bpf documentation

 Documentation/bpf/btf.rst                     | 44 ++++-----
 Documentation/bpf/faq.rst                     | 11 +++
 Documentation/bpf/helpers.rst                 |  7 ++
 Documentation/bpf/index.rst                   | 97 +++----------------
 Documentation/bpf/libbpf/index.rst            |  4 +-
 Documentation/bpf/maps.rst                    |  9 ++
 Documentation/bpf/other.rst                   |  9 ++
 .../bpf/{bpf_lsm.rst => prog_lsm.rst}         |  0
 Documentation/bpf/programs.rst                |  9 ++
 Documentation/bpf/syscall_api.rst             | 11 +++
 Documentation/bpf/test_debug.rst              |  9 ++
 MAINTAINERS                                   |  2 +-
 12 files changed, 103 insertions(+), 109 deletions(-)
 create mode 100644 Documentation/bpf/faq.rst
 create mode 100644 Documentation/bpf/helpers.rst
 create mode 100644 Documentation/bpf/maps.rst
 create mode 100644 Documentation/bpf/other.rst
 rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)
 create mode 100644 Documentation/bpf/programs.rst
 create mode 100644 Documentation/bpf/syscall_api.rst
 create mode 100644 Documentation/bpf/test_debug.rst

-- 
2.33.1

[PATCH bpf-next 1/3] docs: change underline in btf to match style guide

[Dave Tucker]

This changes the type of underline used to follow the guidelines in
Documentation/doc-guide/sphinx.rst which also ensures that the headings
are rendered at the correct level in the HTML sidebar

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
---
 Documentation/bpf/btf.rst | 44 +++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
index d0ec40d00c28..1ebf4c5c7ddc 100644
--- a/Documentation/bpf/btf.rst
+++ b/Documentation/bpf/btf.rst
@@ -3,7 +3,7 @@ BPF Type Format (BTF)
 =====================
 
 1. Introduction
-***************
+===============
 
 BTF (BPF Type Format) is the metadata format which encodes the debug info
 related to BPF program/map. The name BTF was used initially to describe data
@@ -30,7 +30,7 @@ sections are discussed in details in :ref:`BTF_Type_String`.
 .. _BTF_Type_String:
 
 2. BTF Type and String Encoding
-*******************************
+===============================
 
 The file ``include/uapi/linux/btf.h`` provides high-level definition of how
 types/strings are encoded.
@@ -57,13 +57,13 @@ little-endian target. The ``btf_header`` is designed to be extensible with
 generated.
 
 2.1 String Encoding
-===================
+-------------------
 
 The first string in the string section must be a null string. The rest of
 string table is a concatenation of other null-terminated strings.
 
 2.2 Type Encoding
-=================
+-----------------
 
 The type id ``0`` is reserved for ``void`` type. The type section is parsed
 sequentially and type id is assigned to each recognized type starting from id
@@ -504,7 +504,7 @@ valid index (starting from 0) pointing to a member or an argument.
  * ``type``: the type with ``btf_type_tag`` attribute
 
 3. BTF Kernel API
-*****************
+=================
 
 The following bpf syscall command involves BTF:
    * BPF_BTF_LOAD: load a blob of BTF data into kernel
@@ -547,14 +547,14 @@ The workflow typically looks like:
 
 
 3.1 BPF_BTF_LOAD
-================
+----------------
 
 Load a blob of BTF data into kernel. A blob of data, described in
 :ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd``
 is returned to a userspace.
 
 3.2 BPF_MAP_CREATE
-==================
+------------------
 
 A map can be created with ``btf_fd`` and specified key/value type id.::
 
@@ -581,7 +581,7 @@ automatically.
 .. _BPF_Prog_Load:
 
 3.3 BPF_PROG_LOAD
-=================
+-----------------
 
 During prog_load, func_info and line_info can be passed to kernel with proper
 values for the following attributes:
@@ -631,7 +631,7 @@ For line_info, the line number and column number are defined as below:
     #define BPF_LINE_INFO_LINE_COL(line_col)        ((line_col) & 0x3ff)
 
 3.4 BPF_{PROG,MAP}_GET_NEXT_ID
-==============================
+------------------------------
 
 In kernel, every loaded program, map or btf has a unique id. The id won't
 change during the lifetime of a program, map, or btf.
@@ -641,13 +641,13 @@ each command, to user space, for bpf program or maps, respectively, so an
 inspection tool can inspect all programs and maps.
 
 3.5 BPF_{PROG,MAP}_GET_FD_BY_ID
-===============================
+-------------------------------
 
 An introspection tool cannot use id to get details about program or maps.
 A file descriptor needs to be obtained first for reference-counting purpose.
 
 3.6 BPF_OBJ_GET_INFO_BY_FD
-==========================
+--------------------------
 
 Once a program/map fd is acquired, an introspection tool can get the detailed
 information from kernel about this fd, some of which are BTF-related. For
@@ -656,7 +656,7 @@ example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids.
 bpf byte codes, and jited_line_info.
 
 3.7 BPF_BTF_GET_FD_BY_ID
-========================
+------------------------
 
 With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf
 syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with
@@ -668,10 +668,10 @@ tool has full btf knowledge and is able to pretty print map key/values, dump
 func signatures and line info, along with byte/jit codes.
 
 4. ELF File Format Interface
-****************************
+============================
 
 4.1 .BTF section
-================
+----------------
 
 The .BTF section contains type and string data. The format of this section is
 same as the one describe in :ref:`BTF_Type_String`.
@@ -679,7 +679,7 @@ same as the one describe in :ref:`BTF_Type_String`.
 .. _BTF_Ext_Section:
 
 4.2 .BTF.ext section
-====================
+--------------------
 
 The .BTF.ext section encodes func_info and line_info which needs loader
 manipulation before loading into the kernel.
@@ -743,7 +743,7 @@ bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the
 beginning of section (``btf_ext_info_sec->sec_name_off``).
 
 4.2 .BTF_ids section
-====================
+--------------------
 
 The .BTF_ids section encodes BTF ID values that are used within the kernel.
 
@@ -804,10 +804,10 @@ All the BTF ID lists and sets are compiled in the .BTF_ids section and
 resolved during the linking phase of kernel build by ``resolve_btfids`` tool.
 
 5. Using BTF
-************
+============
 
 5.1 bpftool map pretty print
-============================
+----------------------------
 
 With BTF, the map key/value can be printed based on fields rather than simply
 raw bytes. This is especially valuable for large structure or if your data
@@ -849,7 +849,7 @@ bpftool is able to pretty print like below:
       ]
 
 5.2 bpftool prog dump
-=====================
+---------------------
 
 The following is an example showing how func_info and line_info can help prog
 dump with better kernel symbol names, function prototypes and line
@@ -883,7 +883,7 @@ information.::
     [...]
 
 5.3 Verifier Log
-================
+----------------
 
 The following is an example of how line_info can help debugging verification
 failure.::
@@ -909,7 +909,7 @@ failure.::
         R2 offset is outside of the packet
 
 6. BTF Generation
-*****************
+=================
 
 You need latest pahole
 
@@ -1016,6 +1016,6 @@ format.::
             .long   8206                    # Line 8 Col 14
 
 7. Testing
-**********
+==========
 
 Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests.
-- 
2.33.1

[PATCH bpf-next 2/3] docs: Rename bpf_lsm.rst to prog_lsm.rst

[Dave Tucker]

This allows for documentation relating to BPF Program Types to be
matched by the glob pattern prog_* for inclusion in a sphinx toctree

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
---
 Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} | 0
 MAINTAINERS                                     | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)

diff --git a/Documentation/bpf/bpf_lsm.rst b/Documentation/bpf/prog_lsm.rst
similarity index 100%
rename from Documentation/bpf/bpf_lsm.rst
rename to Documentation/bpf/prog_lsm.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index f96aa662ee32..bd690d1ba272 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3529,7 +3529,7 @@ R:	Florent Revest <revest@chromium.org>
 R:	Brendan Jackman <jackmanb@chromium.org>
 L:	bpf@vger.kernel.org
 S:	Maintained
-F:	Documentation/bpf/bpf_lsm.rst
+F:	Documentation/bpf/prog_lsm.rst
 F:	include/linux/bpf_lsm.h
 F:	kernel/bpf/bpf_lsm.c
 F:	security/bpf/
-- 
2.33.1

[PATCH bpf-next 3/3] docs: fix ordering of bpf documentation

[Dave Tucker]

This commit fixes the display of the BPF documentation in the sidebar
when rendered as HTML.

Before this patch, the sidebar would render as follows for some
sections:

| BPF Documentation
  |- BPF Type Format (BTF)
    |- BPF Type Format (BTF)

This was due to creating a heading in index.rst followed by
a sphinx toctree, where the file referenced carries the same
title as the section heading.

To fix this I applied a pattern that has been established in other
subfolders of Documentation:

1. Re-wrote index.rst to have a single toctree
2. Split the sections out in to their own files

Additionally maps.rst and programs.rst make use of a glob pattern to
include map_* or prog_* rst files in their toctree, meaning future map
or program type documentation will be automatically included.

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
---
 Documentation/bpf/faq.rst          | 11 ++++
 Documentation/bpf/helpers.rst      |  7 +++
 Documentation/bpf/index.rst        | 97 ++++--------------------------
 Documentation/bpf/libbpf/index.rst |  4 +-
 Documentation/bpf/maps.rst         |  9 +++
 Documentation/bpf/other.rst        |  9 +++
 Documentation/bpf/programs.rst     |  9 +++
 Documentation/bpf/syscall_api.rst  | 11 ++++
 Documentation/bpf/test_debug.rst   |  9 +++
 9 files changed, 80 insertions(+), 86 deletions(-)
 create mode 100644 Documentation/bpf/faq.rst
 create mode 100644 Documentation/bpf/helpers.rst
 create mode 100644 Documentation/bpf/maps.rst
 create mode 100644 Documentation/bpf/other.rst
 create mode 100644 Documentation/bpf/programs.rst
 create mode 100644 Documentation/bpf/syscall_api.rst
 create mode 100644 Documentation/bpf/test_debug.rst

diff --git a/Documentation/bpf/faq.rst b/Documentation/bpf/faq.rst
new file mode 100644
index 000000000000..a622602ce9ad
--- /dev/null
+++ b/Documentation/bpf/faq.rst
@@ -0,0 +1,11 @@
+================================
+Frequently asked questions (FAQ)
+================================
+
+Two sets of Questions and Answers (Q&A) are maintained.
+
+.. toctree::
+   :maxdepth: 1
+
+   bpf_design_QA
+   bpf_devel_QA
diff --git a/Documentation/bpf/helpers.rst b/Documentation/bpf/helpers.rst
new file mode 100644
index 000000000000..c4ee0cc20dec
--- /dev/null
+++ b/Documentation/bpf/helpers.rst
@@ -0,0 +1,7 @@
+Helper functions
+================
+
+* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs.
+
+.. Links
+.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
\ No newline at end of file
diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index 37f273a7e8b6..413f50101eca 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -12,97 +12,26 @@ BPF instruction-set.
 The Cilium project also maintains a `BPF and XDP Reference Guide`_
 that goes into great technical depth about the BPF Architecture.
 
-libbpf
-======
-
-Documentation/bpf/libbpf/libbpf.rst is a userspace library for loading and interacting with bpf programs.
-
-BPF Type Format (BTF)
-=====================
-
 .. toctree::
    :maxdepth: 1
 
+   libbpf/index
    btf
-
-
-Frequently asked questions (FAQ)
-================================
-
-Two sets of Questions and Answers (Q&A) are maintained.
-
-.. toctree::
-   :maxdepth: 1
-
-   bpf_design_QA
-   bpf_devel_QA
-
-Syscall API
-===========
-
-The primary info for the bpf syscall is available in the `man-pages`_
-for `bpf(2)`_. For more information about the userspace API, see
-Documentation/userspace-api/ebpf/index.rst.
-
-Helper functions
-================
-
-* `bpf-helpers(7)`_ maintains a list of helpers available to eBPF programs.
-
-
-Program types
-=============
-
-.. toctree::
-   :maxdepth: 1
-
-   prog_cgroup_sockopt
-   prog_cgroup_sysctl
-   prog_flow_dissector
-   bpf_lsm
-   prog_sk_lookup
-
-
-Map types
-=========
-
-.. toctree::
-   :maxdepth: 1
-
-   map_cgroup_storage
-
-
-Testing and debugging BPF
-=========================
-
-.. toctree::
-   :maxdepth: 1
-
-   drgn
-   s390
-
-
-Licensing
-=========
-
-.. toctree::
-   :maxdepth: 1
-
+   faq
+   syscall_api
+   helpers
+   programs
+   maps
    bpf_licensing
+   test_debug
+   other
 
+.. only::  subproject and html
 
-Other
-=====
-
-.. toctree::
-   :maxdepth: 1
+   Indices
+   =======
 
-   ringbuf
-   llvm_reloc
+   * :ref:`genindex`
 
 .. Links:
-.. _networking-filter: ../networking/filter.rst
-.. _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
-.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
+.. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
\ No newline at end of file
diff --git a/Documentation/bpf/libbpf/index.rst b/Documentation/bpf/libbpf/index.rst
index 4f8adfc3ab83..4e8c656b539a 100644
--- a/Documentation/bpf/libbpf/index.rst
+++ b/Documentation/bpf/libbpf/index.rst
@@ -3,8 +3,6 @@
 libbpf
 ======
 
-For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_.
-
 .. toctree::
    :maxdepth: 1
 
@@ -14,6 +12,8 @@ For API documentation see the `versioned API documentation site <https://libbpf.
 This is documentation for libbpf, a userspace library for loading and
 interacting with bpf programs.
 
+For API documentation see the `versioned API documentation site <https://libbpf.readthedocs.io/en/latest/api.html>`_.
+
 All general BPF questions, including kernel functionality, libbpf APIs and
 their application, should be sent to bpf@vger.kernel.org mailing list.
 You can `subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the
diff --git a/Documentation/bpf/maps.rst b/Documentation/bpf/maps.rst
new file mode 100644
index 000000000000..2084b0e7cde8
--- /dev/null
+++ b/Documentation/bpf/maps.rst
@@ -0,0 +1,9 @@
+=========
+Map Types
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   map_*
\ No newline at end of file
diff --git a/Documentation/bpf/other.rst b/Documentation/bpf/other.rst
new file mode 100644
index 000000000000..3d61963403b4
--- /dev/null
+++ b/Documentation/bpf/other.rst
@@ -0,0 +1,9 @@
+=====
+Other
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   ringbuf
+   llvm_reloc
\ No newline at end of file
diff --git a/Documentation/bpf/programs.rst b/Documentation/bpf/programs.rst
new file mode 100644
index 000000000000..620eb667ac7a
--- /dev/null
+++ b/Documentation/bpf/programs.rst
@@ -0,0 +1,9 @@
+=============
+Program Types
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   prog_*
diff --git a/Documentation/bpf/syscall_api.rst b/Documentation/bpf/syscall_api.rst
new file mode 100644
index 000000000000..f0a1dff087ad
--- /dev/null
+++ b/Documentation/bpf/syscall_api.rst
@@ -0,0 +1,11 @@
+===========
+Syscall API
+===========
+
+The primary info for the bpf syscall is available in the `man-pages`_
+for `bpf(2)`_. For more information about the userspace API, see
+Documentation/userspace-api/ebpf/index.rst.
+
+.. Links:
+.. _man-pages: https://www.kernel.org/doc/man-pages/
+.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html
\ No newline at end of file
diff --git a/Documentation/bpf/test_debug.rst b/Documentation/bpf/test_debug.rst
new file mode 100644
index 000000000000..ebf0caceb6a6
--- /dev/null
+++ b/Documentation/bpf/test_debug.rst
@@ -0,0 +1,9 @@
+=========================
+Testing and debugging BPF
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+   drgn
+   s390
-- 
2.33.1

Re: [PATCH bpf-next 2/3] docs: Rename bpf_lsm.rst to prog_lsm.rst

[KP Singh]

On Fri, Nov 12, 2021 at 10:18 PM Dave Tucker <dave@dtucker.co.uk> wrote:
>
> This allows for documentation relating to BPF Program Types to be
> matched by the glob pattern prog_* for inclusion in a sphinx toctree
>
> Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
> ---
>  Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} | 0
>  MAINTAINERS                                     | 2 +-
>  2 files changed, 1 insertion(+), 1 deletion(-)
>  rename Documentation/bpf/{bpf_lsm.rst => prog_lsm.rst} (100%)
>
> diff --git a/Documentation/bpf/bpf_lsm.rst b/Documentation/bpf/prog_lsm.rst
> similarity index 100%
> rename from Documentation/bpf/bpf_lsm.rst
> rename to Documentation/bpf/prog_lsm.rst
> diff --git a/MAINTAINERS b/MAINTAINERS
> index f96aa662ee32..bd690d1ba272 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -3529,7 +3529,7 @@ R:        Florent Revest <revest@chromium.org>
>  R:     Brendan Jackman <jackmanb@chromium.org>
>  L:     bpf@vger.kernel.org
>  S:     Maintained
> -F:     Documentation/bpf/bpf_lsm.rst
> +F:     Documentation/bpf/prog_lsm.rst
>  F:     include/linux/bpf_lsm.h
>  F:     kernel/bpf/bpf_lsm.c
>  F:     security/bpf/
> --

Acked-by: KP Singh <kpsingh@kernel.org>

Re: [PATCH bpf-next 0/3] Fix Navigation Issues in Docs

[patchwork-bot+netdevbpf]

Hello:

This series was applied to bpf/bpf-next.git (master)
by Daniel Borkmann <daniel@iogearbox.net>:

On Fri, 12 Nov 2021 21:17:21 +0000 you wrote:
> This patch set fixes a couple of documentation issues that was causing
> some strange behaviour when the sidebar was rendered in the HTML docs.
> 
> 1. The underlines in the BTF document weren't following the docs
> guidelines, which I believe caused an issue rendering the TOC with my
> other patches applied
> 2. Mixing the Sphix toctree with named sections was causing name stutter
> in the sidebar navigation. For example:
> 
> [...]

Here is the summary with links:
  - [bpf-next,1/3] docs: change underline in btf to match style guide
    https://git.kernel.org/bpf/bpf-next/c/3ff36bffaf35
  - [bpf-next,2/3] docs: Rename bpf_lsm.rst to prog_lsm.rst
    https://git.kernel.org/bpf/bpf-next/c/f5b1c2ef43d7
  - [bpf-next,3/3] docs: fix ordering of bpf documentation
    https://git.kernel.org/bpf/bpf-next/c/5931d9a3d052

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html