Commit 5931d9a3 authored by Dave Tucker's avatar Dave Tucker Committed by Daniel Borkmann
Browse files

bpf, docs: Fix ordering of bpf documentation 



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: default avatarDave Tucker <dave@dtucker.co.uk>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
Link: https://lore.kernel.org/bpf/1a1eed800e7b9dc13b458de113a489641519b0cc.1636749493.git.dave@dtucker.co.uk
parent f5b1c2ef

Documentation/bpf/faq.rst

0 → 100644
+11 −0
Original line number Diff line number Diff line 
================================

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

0 → 100644
+7 −0
Original line number Diff line number Diff line 
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
Original line number Diff line number Diff line
@@ -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/
 
 No newline at end of file

Documentation/bpf/libbpf/index.rst

+2 −2
Original line number Diff line number Diff line
@@ -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

Documentation/bpf/maps.rst

0 → 100644
+9 −0
Original line number Diff line number Diff line 
=========

Map Types

=========



.. toctree::

   :maxdepth: 1

   :glob:



   map_*
 
 No newline at end of file