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@xxxxxxxxx> --- 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@xxxxxxxxxxxxxxx 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
