BPF Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH bpf-next 0/3] Autogenerating API documentation
@ 2021-04-29  5:47 grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
                   ` (3 more replies)
  0 siblings, 4 replies; 9+ messages in thread
From: grantseltzer @ 2021-04-29  5:47 UTC (permalink / raw)
  To: andrii, daniel; +Cc: grantseltzer, bpf

This series of patches is meant to start the initiative to document libbpf.
It includes .rst files which are text documentation describing building, 
API naming convention, as well as an index to generated API documentation.

The generated API documentation is enabled by Doxygen, which actually 
parses the code for documentation comment strings and generates XML.
A tool called Sphinx then reads this XML with the help of the breathe
plugin, as well as the above mentioned .rst files and generates beautiful
HTML output.

The goal of this is for readthedocs.io to be able to pick up that generated
documentation which will be made possible with the help of readthedoc's 
github integration and libbpf's official github mirror. Minor setup 
is required in that mirror once this patch series is merged.

grantseltzer (3):
  bpf: Add sphinx documentation build files
  bpf: Add doxygen configuration file
  bpf: Add rst docs for libbpf

 tools/lib/bpf/docs/api.rst                    |  60 ++++
 tools/lib/bpf/docs/build.rst                  |  39 +++
 tools/lib/bpf/docs/conf.py                    |  38 +++
 tools/lib/bpf/docs/index.rst                  |  21 ++
 .../naming_convention.rst}                    |  18 +-
 tools/lib/bpf/docs/sphinx/Makefile            |   9 +
 tools/lib/bpf/docs/sphinx/doxygen/Doxyfile    | 320 ++++++++++++++++++
 tools/lib/bpf/docs/sphinx/requirements.txt    |   1 +
 8 files changed, 499 insertions(+), 7 deletions(-)
 create mode 100644 tools/lib/bpf/docs/api.rst
 create mode 100644 tools/lib/bpf/docs/build.rst
 create mode 100644 tools/lib/bpf/docs/conf.py
 create mode 100644 tools/lib/bpf/docs/index.rst
 rename tools/lib/bpf/{README.rst => docs/naming_convention.rst} (97%)
 create mode 100644 tools/lib/bpf/docs/sphinx/Makefile
 create mode 100644 tools/lib/bpf/docs/sphinx/doxygen/Doxyfile
 create mode 100644 tools/lib/bpf/docs/sphinx/requirements.txt

-- 
2.29.2


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files
  2021-04-29  5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
@ 2021-04-29  5:47 ` grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 2/3] bpf: Add doxygen configuration file grantseltzer
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 9+ messages in thread
From: grantseltzer @ 2021-04-29  5:47 UTC (permalink / raw)
  To: andrii, daniel; +Cc: grantseltzer, bpf

This adds the ability for sphinx, a tool for creating html documentation
to read in .rst documentation files. It also enables it to use the breathe
plugin to read in xml files that are generated by doxygen, a code
documentation tool.

Sphinx pulls in rst or xml documentation and generates pretty html
which also conveniently can be hosted by readthedocs.org.

The requirements.txt file tells sphinx that it requires the 'breathe'
plugin to be installed. breathe is a plugin that acts as the translation
layer between doxygen and sphinx.

Signed-off-by: grantseltzer <grantseltzer@gmail.com>
---
 tools/lib/bpf/docs/conf.py                 | 38 ++++++++++++++++++++++
 tools/lib/bpf/docs/index.rst               | 15 +++++++++
 tools/lib/bpf/docs/sphinx/Makefile         |  9 +++++
 tools/lib/bpf/docs/sphinx/requirements.txt |  1 +
 4 files changed, 63 insertions(+)
 create mode 100644 tools/lib/bpf/docs/conf.py
 create mode 100644 tools/lib/bpf/docs/index.rst
 create mode 100644 tools/lib/bpf/docs/sphinx/Makefile
 create mode 100644 tools/lib/bpf/docs/sphinx/requirements.txt

diff --git a/tools/lib/bpf/docs/conf.py b/tools/lib/bpf/docs/conf.py
new file mode 100644
index 000000000..a67dff0dd
--- /dev/null
+++ b/tools/lib/bpf/docs/conf.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import subprocess
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.todo',
+    'breathe',
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+if read_the_docs_build:
+    subprocess.call('make clean', shell=True)
+    subprocess.call('cd sphinx/doxygen ; doxygen', shell=True)
+
+html_theme = 'sphinx_rtd_theme'
+
+breathe_projects = { "libbpf": "./sphinx/doxygen/build/xml/" }
+breathe_default_project = "libbpf"
+breathe_show_define_initializer = True
+breathe_show_enumvalue_initializer = True
diff --git a/tools/lib/bpf/docs/index.rst b/tools/lib/bpf/docs/index.rst
new file mode 100644
index 000000000..31a6ecfab
--- /dev/null
+++ b/tools/lib/bpf/docs/index.rst
@@ -0,0 +1,15 @@
+libbpf documentation
+=======================================
+
+This is documentation for libbpf, a userspace library for loading and
+interacting with bpf programs.
+
+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 to it `here <http://vger.kernel.org/vger-lists.html#bpf>`_
+and search its archive `here <https://lore.kernel.org/bpf/>`_.
+Please search the archive before asking new questions. It very well might
+be that this was already addressed or answered before.
+
+.. toctree::
+   :caption: Documentation:
diff --git a/tools/lib/bpf/docs/sphinx/Makefile b/tools/lib/bpf/docs/sphinx/Makefile
new file mode 100644
index 000000000..69305958f
--- /dev/null
+++ b/tools/lib/bpf/docs/sphinx/Makefile
@@ -0,0 +1,9 @@
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = ..
+BUILDDIR      = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)"
diff --git a/tools/lib/bpf/docs/sphinx/requirements.txt b/tools/lib/bpf/docs/sphinx/requirements.txt
new file mode 100644
index 000000000..188f51e62
--- /dev/null
+++ b/tools/lib/bpf/docs/sphinx/requirements.txt
@@ -0,0 +1 @@
+breathe
\ No newline at end of file
-- 
2.29.2


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH bpf-next 2/3] bpf: Add doxygen configuration file
  2021-04-29  5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
@ 2021-04-29  5:47 ` grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf grantseltzer
  2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
  3 siblings, 0 replies; 9+ messages in thread
From: grantseltzer @ 2021-04-29  5:47 UTC (permalink / raw)
  To: andrii, daniel; +Cc: grantseltzer, bpf

This adds Doxyfile, the configuration file for Doxygen.
It can be evoked by navigating to it's containing directory
and running `doxygen`. Doxyfile is the default filename.

Evoking sphinx from the tools/lib/bpf/sphinx directory will
also evoke doxygen. This integrates doxygen XML output into
sphinx HTML output.

The majority of these configuraiton settings are defaults,
the main important settings are INPUT, OUTPUT_DIRECTORY,
GENERATE_XML, EXCLUDE_SYMBOLS, and OPTIMIZE_OUTPUT_FOR_C.

Signed-off-by: grantseltzer <grantseltzer@gmail.com>
---
 tools/lib/bpf/docs/sphinx/doxygen/Doxyfile | 320 +++++++++++++++++++++
 1 file changed, 320 insertions(+)
 create mode 100644 tools/lib/bpf/docs/sphinx/doxygen/Doxyfile

diff --git a/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile b/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile
new file mode 100644
index 000000000..905eace7b
--- /dev/null
+++ b/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile
@@ -0,0 +1,320 @@
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "libbpf"
+PROJECT_NUMBER         =
+PROJECT_BRIEF          =
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = ./build
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+OUTPUT_TEXT_DIRECTION  = None
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+JAVADOC_BANNER         = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+PYTHON_DOCSTRING       = YES
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+OPTIMIZE_OUTPUT_SLICE  = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 5
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+NUM_PROC_THREADS       = 1
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+INPUT                  = ../../..
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.java \
+                         *.ii \
+                         *.ixx \
+                         *.ipp \
+                         *.i++ \
+                         *.inl \
+                         *.idl \
+                         *.ddl \
+                         *.odl \
+                         *.h \
+                         *.hh \
+                         *.hxx \
+                         *.hpp \
+                         *.h++ \
+                         *.cs \
+                         *.d \
+                         *.php \
+                         *.php4 \
+                         *.php5 \
+                         *.phtml \
+                         *.inc \
+                         *.m \
+                         *.markdown \
+                         *.md \
+                         *.mm \
+                         *.dox \
+                         *.py \
+                         *.pyw \
+                         *.f90 \
+                         *.f95 \
+                         *.f03 \
+                         *.f08 \
+                         *.f18 \
+                         *.f \
+                         *.for \
+                         *.vhd \
+                         *.vhdl \
+                         *.ucf \
+                         *.qsf \
+                         *.ice
+RECURSIVE              = NO
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        = ___*
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE = YES
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+ALPHABETICAL_INDEX     = YES
+IGNORE_PREFIX          =
+GENERATE_HTML          = NO
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = NO
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+HTML_FORMULA_FORMAT    = png
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+FORMULA_MACROFILE      =
+USE_MATHJAX            = NO
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@2
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         =
+MAKEINDEX_CMD_NAME     = makeindex
+LATEX_MAKEINDEX_CMD    = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
+LATEX_EMOJI_DIRECTORY  =
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_SOURCE_CODE        = NO
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             =
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+CLASS_DIAGRAMS         = YES
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+DOT_UML_DETAILS        = NO
+DOT_WRAP_THRESHOLD     = 17
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
-- 
2.29.2


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf
  2021-04-29  5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
  2021-04-29  5:47 ` [PATCH bpf-next 2/3] bpf: Add doxygen configuration file grantseltzer
@ 2021-04-29  5:47 ` grantseltzer
  2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
  3 siblings, 0 replies; 9+ messages in thread
From: grantseltzer @ 2021-04-29  5:47 UTC (permalink / raw)
  To: andrii, daniel; +Cc: grantseltzer, bpf

This adds rst files containg documentation files relevant for
libbpf development. naming_convention.rst is pulled from the
previous README.rst file. api.rst is an index page that links
to the api documentation generationg from doxygen+breathe.

Signed-off-by: grantseltzer <grantseltzer@gmail.com>
---
 tools/lib/bpf/docs/api.rst                    | 60 +++++++++++++++++++
 tools/lib/bpf/docs/build.rst                  | 39 ++++++++++++
 tools/lib/bpf/docs/index.rst                  |  6 ++
 .../naming_convention.rst}                    | 18 +++---
 4 files changed, 116 insertions(+), 7 deletions(-)
 create mode 100644 tools/lib/bpf/docs/api.rst
 create mode 100644 tools/lib/bpf/docs/build.rst
 rename tools/lib/bpf/{README.rst => docs/naming_convention.rst} (97%)

diff --git a/tools/lib/bpf/docs/api.rst b/tools/lib/bpf/docs/api.rst
new file mode 100644
index 000000000..36bac417b
--- /dev/null
+++ b/tools/lib/bpf/docs/api.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _api:
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 1
+
+LIBBPF API
+==================
+
+
+libbpf.h
+------------------
+
+.. doxygenfile:: libbpf.h
+   :project: libbpf
+
+bpf_core_read.h
+------------------
+
+.. doxygenfile:: bpf_core_read.h
+   :project: libbpf
+
+btf.h
+------------------
+
+.. doxygenfile:: btf.h
+   :project: libbpf
+
+bpf_endian.h
+------------------
+
+.. doxygenfile:: bpf_endian.h
+   :project: libbpf
+
+libbpf_common.h
+------------------
+
+.. doxygenfile:: libbpf_common.h
+   :project: libbpf
+
+hashmap.h
+------------------
+
+.. doxygenfile:: hashmap.h
+   :project: libbpf
+
+
+bpf_helpers.h
+------------------
+
+.. doxygenfile:: bpf_helpers.h
+   :project: libbpf
+
+bpf_helper_defs.h
+------------------
+
+.. doxygenfile:: hashmap.h
+   :project: libbpf
diff --git a/tools/lib/bpf/docs/build.rst b/tools/lib/bpf/docs/build.rst
new file mode 100644
index 000000000..749f96dd2
--- /dev/null
+++ b/tools/lib/bpf/docs/build.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
+.. _build:
+
+Building libbpf
+=======================================
+
+libelf is an internal dependency of libbpf and thus it is required to link
+against and must be installed on the system for applications to work.
+pkg-config is used by default to find libelf, and the program called
+can be overridden with PKG_CONFIG.
+
+If using pkg-config at build time is not desired, it can be disabled by
+setting NO_PKG_CONFIG=1 when calling make.
+
+To build both static libbpf.a and shared libbpf.so:
+
+.. code-block:: bash
+
+    $ cd src
+    $ make
+
+To build only static libbpf.a library in directory build/ and install them
+together with libbpf headers in a staging directory root/:
+
+.. code-block:: bash
+
+    $ cd src
+    $ mkdir build root
+    $ BUILD_STATIC_ONLY=y OBJDIR=build DESTDIR=root make install
+
+To build both static libbpf.a and shared libbpf.so against a custom libelf
+dependency installed in /build/root/ and install them together with libbpf
+headers in a build directory /build/root/:
+
+.. code-block:: bash
+
+    $ cd src
+    $ PKG_CONFIG_PATH=/build/root/lib64/pkgconfig DESTDIR=/build/root make
\ No newline at end of file
diff --git a/tools/lib/bpf/docs/index.rst b/tools/lib/bpf/docs/index.rst
index 31a6ecfab..76bb93580 100644
--- a/tools/lib/bpf/docs/index.rst
+++ b/tools/lib/bpf/docs/index.rst
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+
 libbpf documentation
 =======================================
 
@@ -13,3 +15,7 @@ be that this was already addressed or answered before.
 
 .. toctree::
    :caption: Documentation:
+
+   api
+   naming_convention
+   build
\ No newline at end of file
diff --git a/tools/lib/bpf/README.rst b/tools/lib/bpf/docs/naming_convention.rst
similarity index 97%
rename from tools/lib/bpf/README.rst
rename to tools/lib/bpf/docs/naming_convention.rst
index 8928f7787..6b9ae9701 100644
--- a/tools/lib/bpf/README.rst
+++ b/tools/lib/bpf/docs/naming_convention.rst
@@ -1,6 +1,8 @@
 .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
 
-libbpf API naming convention
+.. _naming_convention:
+
+API naming convention
 ============================
 
 libbpf API provides access to a few logically separated groups of
@@ -76,7 +78,7 @@ Please take a look at Documentation/networking/af_xdp.rst in the Linux
 kernel source tree on how to use XDP sockets and for some common
 mistakes in case you do not get any traffic up to user space.
 
-libbpf ABI
+ABI
 ==========
 
 libbpf can be both linked statically or used as DSO. To avoid possible
@@ -116,7 +118,8 @@ This bump in ABI version is at most once per kernel development cycle.
 
 For example, if current state of ``libbpf.map`` is:
 
-.. code-block::
+.. code-block:: c
+
         LIBBPF_0.0.1 {
         	global:
                         bpf_func_a;
@@ -128,7 +131,8 @@ For example, if current state of ``libbpf.map`` is:
 , and a new symbol ``bpf_func_c`` is being introduced, then
 ``libbpf.map`` should be changed like this:
 
-.. code-block::
+.. code-block:: c
+
         LIBBPF_0.0.1 {
         	global:
                         bpf_func_a;
@@ -148,7 +152,7 @@ Format of version script and ways to handle ABI changes, including
 incompatible ones, described in details in [1].
 
 Stand-alone build
-=================
+-------------------
 
 Under https://github.com/libbpf/libbpf there is a (semi-)automated
 mirror of the mainline's version of libbpf for a stand-alone build.
@@ -157,12 +161,12 @@ However, all changes to libbpf's code base must be upstreamed through
 the mainline kernel tree.
 
 License
-=======
+-------------------
 
 libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause.
 
 Links
-=====
+-------------------
 
 [1] https://www.akkadia.org/drepper/dsohowto.pdf
     (Chapter 3. Maintaining APIs and ABIs).
-- 
2.29.2


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH bpf-next 0/3] Autogenerating API documentation
  2021-04-29  5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
                   ` (2 preceding siblings ...)
  2021-04-29  5:47 ` [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf grantseltzer
@ 2021-04-29 22:57 ` Jonathan Corbet
  2021-04-30 14:04   ` Grant Seltzer Richman
  3 siblings, 1 reply; 9+ messages in thread
From: Jonathan Corbet @ 2021-04-29 22:57 UTC (permalink / raw)
  To: grantseltzer, andrii, daniel; +Cc: grantseltzer, bpf

grantseltzer <grantseltzer@gmail.com> writes:

> This series of patches is meant to start the initiative to document libbpf.
> It includes .rst files which are text documentation describing building, 
> API naming convention, as well as an index to generated API documentation.

So I'm totally in favor of documenting libbpf...

> The generated API documentation is enabled by Doxygen, which actually 
> parses the code for documentation comment strings and generates XML.
> A tool called Sphinx then reads this XML with the help of the breathe
> plugin, as well as the above mentioned .rst files and generates beautiful
> HTML output.
>
> The goal of this is for readthedocs.io to be able to pick up that generated
> documentation which will be made possible with the help of readthedoc's 
> github integration and libbpf's official github mirror. Minor setup 
> is required in that mirror once this patch series is merged.

...but I do have to wonder why you are doing something outside of the
kernel's documentation system, which just happens to be based on a tool
called Sphinx.  It would be Really Nice to have this documentation part
of our doc tree; it would also be good to not bring in yet another tool
for building kernel docs.

Do you really need to do your own thing here?

Thanks,

jon

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH bpf-next 0/3] Autogenerating API documentation
  2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
@ 2021-04-30 14:04   ` Grant Seltzer Richman
  2021-04-30 14:22     ` Jonathan Corbet
  0 siblings, 1 reply; 9+ messages in thread
From: Grant Seltzer Richman @ 2021-04-30 14:04 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: Andrii Nakryiko, Daniel Borkmann, bpf

On Thu, Apr 29, 2021 at 6:57 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> grantseltzer <grantseltzer@gmail.com> writes:
>
> > This series of patches is meant to start the initiative to document libbpf.
> > It includes .rst files which are text documentation describing building,
> > API naming convention, as well as an index to generated API documentation.
>
> So I'm totally in favor of documenting libbpf...
>
> > The generated API documentation is enabled by Doxygen, which actually
> > parses the code for documentation comment strings and generates XML.
> > A tool called Sphinx then reads this XML with the help of the breathe
> > plugin, as well as the above mentioned .rst files and generates beautiful
> > HTML output.
> >
> > The goal of this is for readthedocs.io to be able to pick up that generated
> > documentation which will be made possible with the help of readthedoc's
> > github integration and libbpf's official github mirror. Minor setup
> > is required in that mirror once this patch series is merged.
>
> ...but I do have to wonder why you are doing something outside of the
> kernel's documentation system, which just happens to be based on a tool
> called Sphinx.  It would be Really Nice to have this documentation part
> of our doc tree; it would also be good to not bring in yet another tool
> for building kernel docs.
>
> Do you really need to do your own thing here?

Hm, yes I do agree that it'd be nice to use existing tooling but I
just have a couple concerns for this but please point me in the right
direction because i'm sure i'm missing something. I was told to ask on
the linux-doc mailing list because you'd have valuable input anway.
This is based on reading
https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments

1. We'd want the ability to pull documentation from the code itself to
make it so documentation never falls out of date with code. Based on
the docs on kernel.org/doc it seems that we'd have to be explicit with
specifying which functions/types are included in an .rst file and
submit a patch to update the documentation everytime the libbpf api
changes. Perhaps if this isn't a thing already I can figure out how to
contribute it.

2. Would it be possible (or necessary) to separate libbpf
documentation from the kernel readthedocs page since libbpf isn't part
of the kernel?

Thanks so much,
Grant

> Thanks,
>
> jon

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH bpf-next 0/3] Autogenerating API documentation
  2021-04-30 14:04   ` Grant Seltzer Richman
@ 2021-04-30 14:22     ` Jonathan Corbet
  2021-04-30 14:27       ` Grant Seltzer Richman
  0 siblings, 1 reply; 9+ messages in thread
From: Jonathan Corbet @ 2021-04-30 14:22 UTC (permalink / raw)
  To: Grant Seltzer Richman; +Cc: Andrii Nakryiko, Daniel Borkmann, bpf

Grant Seltzer Richman <grantseltzer@gmail.com> writes:

> Hm, yes I do agree that it'd be nice to use existing tooling but I
> just have a couple concerns for this but please point me in the right
> direction because i'm sure i'm missing something. I was told to ask on
> the linux-doc mailing list because you'd have valuable input anway.
> This is based on reading
> https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments
>
> 1. We'd want the ability to pull documentation from the code itself to
> make it so documentation never falls out of date with code. Based on
> the docs on kernel.org/doc it seems that we'd have to be explicit with
> specifying which functions/types are included in an .rst file and
> submit a patch to update the documentation everytime the libbpf api
> changes. Perhaps if this isn't a thing already I can figure out how to
> contribute it.

No, you can tell it to pull out docs for all of the functions in a given
file.  You only need to name things if you want to narrow things down.

> 2. Would it be possible (or necessary) to separate libbpf
> documentation from the kernel readthedocs page since libbpf isn't part
> of the kernel?

It could certainly be built as a separate "book", as are many of the
kernel books now.  I could see it as something that gets pulled into the
user-space API book, but there could also perhaps be an argument made
for creating a new "libraries" book instead.

Thanks,

jon

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH bpf-next 0/3] Autogenerating API documentation
  2021-04-30 14:22     ` Jonathan Corbet
@ 2021-04-30 14:27       ` Grant Seltzer Richman
  2021-04-30 17:30         ` Andrii Nakryiko
  0 siblings, 1 reply; 9+ messages in thread
From: Grant Seltzer Richman @ 2021-04-30 14:27 UTC (permalink / raw)
  To: Jonathan Corbet; +Cc: Andrii Nakryiko, Daniel Borkmann, bpf

On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Grant Seltzer Richman <grantseltzer@gmail.com> writes:
>
> > Hm, yes I do agree that it'd be nice to use existing tooling but I
> > just have a couple concerns for this but please point me in the right
> > direction because i'm sure i'm missing something. I was told to ask on
> > the linux-doc mailing list because you'd have valuable input anway.
> > This is based on reading
> > https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments
> >
> > 1. We'd want the ability to pull documentation from the code itself to
> > make it so documentation never falls out of date with code. Based on
> > the docs on kernel.org/doc it seems that we'd have to be explicit with
> > specifying which functions/types are included in an .rst file and
> > submit a patch to update the documentation everytime the libbpf api
> > changes. Perhaps if this isn't a thing already I can figure out how to
> > contribute it.
>
> No, you can tell it to pull out docs for all of the functions in a given
> file.  You only need to name things if you want to narrow things down.

Alright, I will figure out how to do this and adjust the patch
accordingly. My biggest overall goal is making it as easy as possible
to contribute documentation. I think even adding just one doc string
above an API function is a great opportunity for new contributors to
familiarize themselves with the mailing list/patch process.

>
> > 2. Would it be possible (or necessary) to separate libbpf
> > documentation from the kernel readthedocs page since libbpf isn't part
> > of the kernel?
>
> It could certainly be built as a separate "book", as are many of the
> kernel books now.  I could see it as something that gets pulled into the
> user-space API book, but there could also perhaps be an argument made
> for creating a new "libraries" book instead.

Yea if I can figure this out for the libbpf API it'd be great to
replicate it for any API!

>
> Thanks,
>
> jon

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH bpf-next 0/3] Autogenerating API documentation
  2021-04-30 14:27       ` Grant Seltzer Richman
@ 2021-04-30 17:30         ` Andrii Nakryiko
  0 siblings, 0 replies; 9+ messages in thread
From: Andrii Nakryiko @ 2021-04-30 17:30 UTC (permalink / raw)
  To: Grant Seltzer Richman
  Cc: Jonathan Corbet, Andrii Nakryiko, Daniel Borkmann, bpf

On Fri, Apr 30, 2021 at 7:27 AM Grant Seltzer Richman
<grantseltzer@gmail.com> wrote:
>
> On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > Grant Seltzer Richman <grantseltzer@gmail.com> writes:
> >
> > > Hm, yes I do agree that it'd be nice to use existing tooling but I
> > > just have a couple concerns for this but please point me in the right
> > > direction because i'm sure i'm missing something. I was told to ask on
> > > the linux-doc mailing list because you'd have valuable input anway.
> > > This is based on reading
> > > https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments
> > >
> > > 1. We'd want the ability to pull documentation from the code itself to
> > > make it so documentation never falls out of date with code. Based on
> > > the docs on kernel.org/doc it seems that we'd have to be explicit with
> > > specifying which functions/types are included in an .rst file and
> > > submit a patch to update the documentation everytime the libbpf api
> > > changes. Perhaps if this isn't a thing already I can figure out how to
> > > contribute it.
> >
> > No, you can tell it to pull out docs for all of the functions in a given
> > file.  You only need to name things if you want to narrow things down.
>
> Alright, I will figure out how to do this and adjust the patch
> accordingly. My biggest overall goal is making it as easy as possible
> to contribute documentation. I think even adding just one doc string
> above an API function is a great opportunity for new contributors to
> familiarize themselves with the mailing list/patch process.
>
> >
> > > 2. Would it be possible (or necessary) to separate libbpf
> > > documentation from the kernel readthedocs page since libbpf isn't part
> > > of the kernel?
> >
> > It could certainly be built as a separate "book", as are many of the
> > kernel books now.  I could see it as something that gets pulled into the
> > user-space API book, but there could also perhaps be an argument made
> > for creating a new "libraries" book instead.
>
> Yea if I can figure this out for the libbpf API it'd be great to
> replicate it for any API!

It would be great if it was possible to have this libbpf
auto-generated documentation as part of the kernel documentation, but
also be able to generate and export it into our Github mirror to be
pulled by readthedocs.io. If that can be done, it would be the best of
both kernel and external worlds. We have a sync script that already
auto-generates and checks in BPF helpers header, so we have a
precedent of checking in auto-generated stuff into Github. So it's
mostly about figuring out the mechanics of doc generation.

>
> >
> > Thanks,
> >
> > jon

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, back to index

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-04-29  5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
2021-04-29  5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
2021-04-29  5:47 ` [PATCH bpf-next 2/3] bpf: Add doxygen configuration file grantseltzer
2021-04-29  5:47 ` [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf grantseltzer
2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
2021-04-30 14:04   ` Grant Seltzer Richman
2021-04-30 14:22     ` Jonathan Corbet
2021-04-30 14:27       ` Grant Seltzer Richman
2021-04-30 17:30         ` Andrii Nakryiko

BPF Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/bpf/0 bpf/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 bpf bpf/ https://lore.kernel.org/bpf \
		bpf@vger.kernel.org
	public-inbox-index bpf

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.bpf


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git