docs: add documentation

Signed-off-by: Timo Beckers <[email protected]>

.gitignore

@@ -12,3 +12,10 @@
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
+
+# Python
+__pycache__
+
+# Documentation
+docs/build
+docs/site

docs/Pipfile

@@ -0,0 +1,18 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+mkdocs = "*"
+pymdown-extensions = "*"
+mkdocs-material = "*"
+mkdocs-macros-plugin = "*"
+mkdocs-git-revision-date-localized-plugin = "*"
+mkdocs-git-authors-plugin = "*"
+
+[dev-packages]
+
+# Whatever Netlify's Ubuntu version uses.
+[requires]
+python_version = "3.8"

docs/README.md

@@ -0,0 +1,21 @@
+# epbf-go documentation
+
+The project uses Pipenv to manage its dependencies, which will automatically create a Python virtualenv when invoked
+from this subdirectory. Follow your distribution's documentation for installing `pipenv`. You may also need `pyenv`
+to install a different Python version if your distribution doesn't provide the version specified in the `Pipfile`.
+
+To create a Python venv and install dependencies:
+
+`$ pipenv install`
+
+To enter the venv and use its corresponding interpreter:
+
+`$ pipenv shell`
+
+You may now run a development copy of the documentation locally:
+
+`$ mkdocs serve`
+
+.. or build all assets and output a full copy of the website ready for hosting:
+
+`$ mkdocs build`

docs/ebpf.py

@@ -0,0 +1,230 @@
+"""Macro definitions for documentation."""
+
+# Use built-in 'list' type when upgrading to Python 3.9.
+
+import glob
+import os
+import textwrap
+from io import TextIOWrapper
+from typing import List
+from urllib.parse import ParseResult, urlparse
+
+from mkdocs_macros.plugin import MacrosPlugin
+
+
+def define_env(env: MacrosPlugin):
+    """
+    Define the mkdocs-macros-plugin environment.
+
+    This function is called on setup. 'env' can be interacted with
+    for defining variables, macros and filters.
+
+    - variables: the dictionary that contains the environment variables
+    - macro: a decorator function, to declare a macro.
+    - filter: a function with one or more arguments, used to perform a
+    transformation
+    """
+    # Values can be overridden in mkdocs.yml:extras.
+    go_examples_path: str = env.variables.get(
+        "go_examples_path", "examples/*.go"
+    )
+    godoc_url: ParseResult = urlparse(
+        env.variables.get(
+            "godoc_url", "https://pkg.go.dev/github.com/cilium/ebpf"
+        )
+    )
+
+    c_examples_path: str = env.variables.get("c_examples_path", "examples/*.c")
+
+    @env.macro
+    def godoc(sym: str, short: bool = False):
+        """
+        Generate a godoc link based on the configured godoc_url.
+
+        `sym` is the symbol to link to. A dot '.' separator means it's a method
+        on another type. Forward slashes '/' can be used to navigate to symbols
+        in subpackages.
+
+        For example:
+        - CollectionSpec.LoadAndAssign
+        - link/Link
+        - btf/Spec.TypeByID
+
+        `short` renders only the symbol name.
+        """
+        if len(godoc_url) == 0:
+            raise ValueError("Empty godoc url")
+
+        # Support referring to symbols in subpackages.
+        subpkg = os.path.dirname(sym)
+        # Symbol name including dots for struct methods. (e.g. Map.Get)
+        name = os.path.basename(sym)
+
+        # Python's urljoin() expects the base path to have a trailing slash for
+        # it to correctly append subdirs. Use urlparse instead, and interact
+        # with the URL's components individually.
+        url = godoc_url._replace(
+            path=os.path.join(godoc_url.path, subpkg),
+            # Anchor token appearing after the # in the URL.
+            fragment=name,
+        ).geturl()
+
+        text = name
+        if short:
+            text = text.split(".")[-1]
+
+        return f"[:fontawesome-brands-golang: `{text}`]({url})"
+
+    @env.macro
+    def go_example(*args, **kwargs):
+        """
+        Include the body of a Go code example.
+
+        See docstring of code_example() for details.
+        """
+        return code_example(
+            *args, **kwargs, language="go", path=go_examples_path
+        )
+
+    @env.macro
+    def c_example(*args, **kwargs):
+        """
+        Include the body of a C code example.
+
+        See docstring of `code_example` for details.
+        """
+        return code_example(
+            *args, **kwargs, language="c", path=c_examples_path
+        )
+
+
+def code_example(
+    symbol: str,
+    title: str = None,
+    language: str = "",
+    lines: bool = True,
+    signature: bool = False,
+    path: str = "",
+) -> str:
+    """
+    Include the body of a code example.
+
+    `symbol` takes the name of the function or snippet to include.
+    `title` is rendered as a title at the top of the snippet.
+    `language` is the
+    `lines` controls rendering line numbers.
+    allowing included code snippets to be used as content tabs.
+    `signature` controls whether or not the function signature and brackets
+    are included.
+    `path` specifies the include path that may contain globs.
+    """
+    opts: List[str] = []
+    if lines:
+        opts.append("linenums='1'")
+    if title:
+        opts.append(f"title='{title}'")
+
+    if signature:
+        body = full_body(path, symbol)
+    else:
+        body = inner_body(path, symbol)
+
+    out = f"``` {language} {' '. join(opts)}\n{body}```"
+
+    return out
+
+
+def inner_body(path: str, sym: str) -> str:
+    """
+    Get the inner body of sym, using default delimiters.
+
+    First and last lines (so, function signature and closing bracket) are
+    stripped, the remaining body dedented.
+    """
+    out = _search_body(path, sym)
+    if len(out) < 2:
+        raise ValueError(
+            f"Need at least two lines to get inner body for symbol {sym}"
+        )
+
+    return textwrap.dedent("".join(out[1:-1]))
+
+
+def full_body(path: str, sym: str) -> str:
+    """Get the full body of sym, using default delimiters, dedented."""
+    out = _search_body(path, sym)
+
+    return textwrap.dedent("".join(out))
+
+
+def _get_body(
+    f: TextIOWrapper, sym: str, start: str = "{", end: str = "}"
+) -> List[str]:
+    """
+    Extract a body of text between sym and start/end delimiters.
+
+    Tailored to finding function bodies of C-family programming languages with
+    curly braces.
+
+    The starting line of the body must contain sym prefixed by a space, with
+    d_start appearing on the same line, for example " Foo() {". Further
+    occurrences of "{" and its closing counterpart "}" are tracked, and the
+    lines between and including the final "}" are returned.
+    """
+    found = False
+    stack = 0
+    lines = []
+
+    sym = " " + sym
+
+    for line in f.readlines():
+        if not found:
+            # Skip current line if we're not in a body and the current line
+            # doesn't contain a start delimiter.
+            if sym not in line:
+                continue
+
+            found = True
+
+        # Count the amount of start delimiters.
+        stack += line.count(start)
+
+        if stack == 0:
+            # No opening delimiter found, ignore the line.
+            found = False
+            continue
+
+        lines.append(line)
+
+        # Count the amount of end delimiters and stop if we've escaped the
+        # current scope.
+        stack -= line.count(end)
+        if stack <= 0:
+            break
+
+    # Rewind the file for reuse.
+    f.seek(0)
+
+    if stack > 0:
+        raise LookupError(f"No end delimiter for {sym}")
+
+    if len(lines) == 0:
+        raise LookupError(f"Symbol {sym} not found")
+
+    return lines
+
+
+def _search_body(path: str, sym: str) -> List[str]:
+    """Find the body of the given symbol in a path glob."""
+    files = glob.glob(path)
+    if len(files) == 0:
+        raise LookupError(f"Path {path} did not match any files")
+
+    for file in files:
+        with open(file, mode="r") as f:
+            try:
+                return _get_body(f, sym)
+            except LookupError:
+                continue
+
+    raise LookupError(f"Symbol {sym} not found in any of {files}")

docs/ebpf/about.md

@@ -0,0 +1,9 @@
+# About {{ proj }}
+
+The project was initially created in 2017 as [`newtools/ebpf`](https://github.com/newtools/ebpf) by [Nathan
+Sweet](https://github.com/nathanjsweet). It quickly gained traction within the Go community for projects that couldn't
+or wouldn't build upon the CGo-based BCC bindings at the time (`gobpf`).
+
+Since then, it's been widely adopted by hundreds of open-source projects, by large industry players, and by startups
+building their businesses on top of eBPF alike. Today, it continues to evolve thanks to its thriving community and close
+collaboration with the upstream Linux project.

docs/ebpf/btf/index.md

@@ -0,0 +1 @@
+Document package btf here.

docs/ebpf/features/index.md

@@ -0,0 +1 @@
+Document package features here.

docs/ebpf/getting-started/further-reading.md

@@ -0,0 +1 @@
+Include useful links to external documentation here.