[bpf-next,1/3] bpf: Add sphinx documentation build files

Commit Message

Grant Seltzer Richman April 29, 2021, 5:47 a.m. UTC

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 <[e-mail]>
---
 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

Patch

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 [e-mail] 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