Skip to content

Commit 995ac78

Browse files
ti-moti-mo
committed
docs: introduce mkdocs-based documentation website boilerplate
This commit introduces an mkdocs-based documentation boilerplate, containing: - The mkdocs configuration (mkdocs.yml), defining the site's navigation and ToC - Python dependency management using pipenv - Netlify configuration for automated builds & deploys - eBee emoji - Macros for easily including real code examples into documentation. These examples get built in CI, ensuring they don't rot when API or dependencies change. - A glossary for commonly-used terms in BPF land. - Custom admonition for rendering warnings about incomplete documentation sections using '!!! incomplete'. Signed-off-by: Timo Beckers <[email protected]>
1 parent 25426af commit 995ac78

File tree

16 files changed

+2052
-0
lines changed

16 files changed

+2052
-0
lines changed

‎.github/workflows/ci.yml

+36
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ env:
1010
CI_MIN_CLANG_VERSION: '11'
1111
go_version: '~1.21'
1212
prev_go_version: '~1.20'
13+
# This needs to match whatever Netlify supports.
14+
# Also defined in Pipfile.
15+
python_version: '~3.8'
1316

1417
concurrency:
1518
group: ${{ github.workflow }}-${{ github.ref }}
@@ -70,6 +73,39 @@ jobs:
7073
go build -v ./...
7174
go test -c -o /dev/null ./... >/dev/null
7275
76+
build-docs:
77+
name: Build Documentation
78+
runs-on: ubuntu-22.04
79+
timeout-minutes: 10
80+
steps:
81+
- uses: actions/checkout@v3
82+
with:
83+
# The mkdocs git-authors plugin needs access to the full revision
84+
# history to correctly generate its statistics.
85+
fetch-depth: 0
86+
87+
- name: Set up Go
88+
uses: actions/setup-go@v4
89+
with:
90+
go-version: '${{ env.go_version }}'
91+
92+
- name: Set up Python
93+
uses: actions/setup-python@v4
94+
with:
95+
python-version: '${{ env.python_version }}'
96+
cache: 'pipenv'
97+
98+
- name: Install pipenv
99+
run: pip3 install pipenv
100+
101+
- name: Install Dependencies
102+
run: pipenv install
103+
working-directory: ./docs
104+
105+
- name: Build Documentation
106+
run: make build
107+
working-directory: ./docs
108+
73109
test-on-prev-go:
74110
name: Run tests on previous stable Go
75111
runs-on: ubuntu-latest-4cores-16gb

‎docs/.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Python
2+
__pycache__
3+
4+
# Build output
5+
build/
6+
site/

‎docs/Makefile

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
build: pipenv
2+
@# Run a production build of the documentation. Strict mode makes warnings fatal.
3+
pipenv run mkdocs build --strict
4+
5+
@# Build main packages, discarding build output.
6+
go build -v ./...
7+
8+
@# Build _test.go files containing Doc* functions, don't execute tests.
9+
go test -c -o /dev/null ./... >/dev/null
10+
11+
preview: pipenv
12+
pipenv run mkdocs serve
13+
14+
shell: pipenv
15+
pipenv shell
16+
17+
pipenv:
18+
ifeq (, $(shell command -v pipenv 2> /dev/null))
19+
$(error "pipenv is not installed, exiting..")
20+
endif
21+
22+
.PHONY: pipenv

‎docs/Pipfile

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[[source]]
2+
url = "https://pypi.org/simple"
3+
verify_ssl = true
4+
name = "pypi"
5+
6+
[packages]
7+
mkdocs = "*"
8+
pymdown-extensions = "*"
9+
mkdocs-material = "9.3.2"
10+
mkdocs-macros-plugin = "*"
11+
mkdocs-git-revision-date-localized-plugin = "*"
12+
mkdocs-git-authors-plugin = "*"
13+
14+
[dev-packages]
15+
16+
# Whatever Netlify's Ubuntu version uses.
17+
[requires]
18+
python_version = "3.8"

‎docs/Pipfile.lock

+617
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/README.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# epbf-go documentation
2+
3+
The documentation project uses Pipenv to manage its dependencies, which will
4+
automatically create a Python virtualenv when invoked from this subdirectory.
5+
Follow your distribution's documentation for installing `pipenv`. You may also
6+
need `pyenv` to install a different Python version if your distribution doesn't
7+
provide the version specified in the `Pipfile`.
8+
9+
Host a live preview of the documentation at http://127.0.0.1:8000:
10+
11+
`make preview`
12+
13+
Build the documentation, output to the site/ directory. This is a self-contained
14+
production copy that can be uploaded to hosting.
15+
16+
`make build`
17+
18+
To enter the virtualenv with all the documentation's Python dependencies
19+
installed:
20+
21+
`make shell`

‎docs/ebpf/stylesheets/extra.css

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
/* :progress-wrench:
2+
Custom 'incomplete' admonition for sections that need work or maintenance.
3+
Create blocks using '!!! incomplete'.
4+
*/
5+
:root {
6+
--md-admonition-icon--incomplete: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 2.03v2.02c4.39.54 7.5 4.53 6.96 8.92-.46 3.64-3.32 6.53-6.96 6.96v2c5.5-.55 9.5-5.43 8.95-10.93-.45-4.75-4.22-8.5-8.95-8.97m-2 .03c-1.95.19-3.81.94-5.33 2.2L7.1 5.74c1.12-.9 2.47-1.48 3.9-1.68v-2M4.26 5.67A9.885 9.885 0 0 0 2.05 11h2c.19-1.42.75-2.77 1.64-3.9L4.26 5.67M2.06 13c.2 1.96.97 3.81 2.21 5.33l1.42-1.43A8.002 8.002 0 0 1 4.06 13h-2m5.04 5.37-1.43 1.37A9.994 9.994 0 0 0 11 22v-2a8.002 8.002 0 0 1-3.9-1.63m9.72-3.18-4.11-4.11c.41-1.04.18-2.26-.68-3.11-.9-.91-2.25-1.09-3.34-.59l1.94 1.94-1.35 1.36-1.99-1.95c-.54 1.09-.29 2.44.59 3.35.86.86 2.08 1.08 3.12.68l4.11 4.1c.18.19.45.19.63 0l1.04-1.03c.22-.18.22-.5.04-.64Z"/></svg>')
7+
}
8+
9+
.md-typeset .admonition.incomplete,
10+
.md-typeset details.incomplete {
11+
border-color: rgb(255, 204, 77);
12+
}
13+
14+
.md-typeset .incomplete>.admonition-title,
15+
.md-typeset .incomplete>summary {
16+
background-color: rgba(255, 204, 77, 0.1);
17+
}
18+
19+
.md-typeset .incomplete>.admonition-title::before,
20+
.md-typeset .incomplete>summary::before {
21+
background-color: rgb(255, 204, 77);
22+
-webkit-mask-image: var(--md-admonition-icon--incomplete);
23+
mask-image: var(--md-admonition-icon--incomplete);
24+
}
25+
26+
/* gp and go are the classes used for prompt and output in shell-session code
27+
blocks. Prevent these from being highlighted as it hurts UX.
28+
*/
29+
.highlight .gp,
30+
.highlight .go {
31+
user-select: none;
32+
}

‎docs/includes/glossary.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<!-- This snippet is automatically included on every page and takes care of automatically highlighting terminology. -->
2+
*[Program]: Instructions that can be loaded and attached to one or more hooks in the Linux kernel.
3+
*[Map]: Shared piece of memory between userspace and an eBPF program loaded into the kernel.
4+
*[Link]: Connection between a Program and a hook/event in the kernel.
5+
*[BTF]: BPF Type Format; a description of all data types present in the Linux kernel an eBPF object.
6+
*[ELF]: Executable and Linkable Format, a container format used for compiled eBPF programs.
7+
*[Spec]: Unrealized blueprint of an eBPF resource, e.g. MapSpec, ProgramSpec, btf.Spec.
8+
*[CollectionSpec]: Bundle of ProgramSpecs, MapSpecs and a btf.Spec. Direct result of loading an eBPF ELF.
9+
*[Collection]: Bundle of Maps and Programs that were loaded into the kernel. Direct result of instantiating (loading into the kernel) a CollectionSpec.
10+
*[bpffs]: Birtual filesystem for 'pinning' references to eBPF resources in an familiar file hierarchy. Usually mounted at /sys/fs/bpf, but many individual instances can be mounted.
11+
*[helper]: A piece of logic provided by the kernel. Read a map value, redirect a packet, etc.
12+
*[kfunc]: An extensible evolution of the BPF helper mechanism. Can be dynamically provided by kernel modules. Not specified in UAPI.
13+
*[XDP]: eXpress Data Path, a high-performance eBPF-powered data path. Only has a receive hook.
14+
*[bpf2go]: Convenience utility to compile eBPF C using clang and generate a Go skeleton.
15+
*[libbpf]: A library for writing kernel- and user space BPF programs in C, developed by the upstream Linux project.

0 commit comments

Comments
 (0)