Skip to contentSkip to conversation

Fix Navigation Issues in Docs

PATCH Applied Dave Tucker 3 participants 6 messages Nov 12, 2021 – Nov 17, 2021

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover Fix Navigation Issues in Docs

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
Signature · 1 line
2.33.1
#1 lore raw

PATCH 1/3 docs: change underline in btf to match style guide

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

---
 Documentation/bpf/btf.rst | 44 +++++++++++++++++++--------------------
 1 file changed, 22 insertions(+), 22 deletions(-)
Documentation/bpf/btf.rst +22 -22
index d0ec40d00c28..1ebf4c5c7ddc 100644
@@ -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.
Signature · 1 line
2.33.1
#2 lore raw

PATCH 2/3 docs: Rename bpf_lsm.rst to prog_lsm.rst

In reply to 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

---
 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%)
Documentation/bpf/prog_lsm.rst renamed from Documentation/bpf/bpf_lsm.rst +0 -0
similarity index 100%
rename from Documentation/bpf/bpf_lsm.rst
rename to Documentation/bpf/prog_lsm.rst
MAINTAINERS +1 -1
index f96aa662ee32..bd690d1ba272 100644
@@ -3529,7 +3529,7 @@ R:	Florent Revest <[email protected]>
 R:	Brendan Jackman <[email protected]>
 L:	[email protected]
 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/
Signature · 1 line
2.33.1
maintainer Acked-by on v1 2/3
#3 lore raw

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

Quoted 20 lines · 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

---
 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%)
Documentation/bpf/prog_lsm.rst renamed from Documentation/bpf/bpf_lsm.rst +0 -0
similarity index 100%
rename from Documentation/bpf/bpf_lsm.rst
rename to Documentation/bpf/prog_lsm.rst
MAINTAINERS +0 -0
index f96aa662ee32..bd690d1ba272 100644

MAINTAINERS R: Florent Revest <[email protected]>

Quoted 9 lines
MAINTAINERS +1 -2
@@ -3529,7 +3529,7 @@ R:        Florent Revest <[email protected]>
 R:     Brendan Jackman <[email protected]>
 L:     [email protected]
 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/
--
#4 lore raw

PATCH 3/3 docs: fix ordering of bpf documentation

In reply to 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.

---
 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
Documentation/bpf/faq.rst new file +11 -0
new file mode 100644
index 000000000000..a622602ce9ad
@@ -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
Documentation/bpf/helpers.rst new file +7 -0
new file mode 100644
index 000000000000..c4ee0cc20dec
@@ -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
Documentation/bpf/index.rst +13 -84

111 lines not on this page · raw message

Documentation/bpf/libbpf/index.rst +2 -2
index 4f8adfc3ab83..4e8c656b539a 100644
@@ -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 [email protected] mailing list.
 You can `subscribe <http://vger.kernel.org/vger-lists.html#bpf>`_ to the
Documentation/bpf/maps.rst new file +9 -0
new file mode 100644
index 000000000000..2084b0e7cde8
@@ -0,0 +1,9 @@
+=========
+Map Types
+=========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   map_*
\ No newline at end of file
Documentation/bpf/other.rst new file +9 -0
new file mode 100644
index 000000000000..3d61963403b4
@@ -0,0 +1,9 @@
+=====
+Other
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   ringbuf
+   llvm_reloc
\ No newline at end of file
Documentation/bpf/programs.rst new file +9 -0
new file mode 100644
index 000000000000..620eb667ac7a
@@ -0,0 +1,9 @@
+=============
+Program Types
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   prog_*
Documentation/bpf/syscall_api.rst new file +11 -0
new file mode 100644
index 000000000000..f0a1dff087ad
@@ -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
Documentation/bpf/test_debug.rst new file +9 -0
new file mode 100644
index 000000000000..ebf0caceb6a6
@@ -0,0 +1,9 @@
+=========================
+Testing and debugging BPF
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+   drgn
+   s390
Signature · 1 line
2.33.1
#5 lore raw
In reply to Dave Tucker
This series was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:

Hello:

This series was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:

Quoted 10 lines · 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!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html