This section describes how to modify the related documentation around bpfman. All bpfman's documentation is written in Markdown, and leverages mkdocs to generate a static site, which is hosted on netlify.
If this is the first time building using
mkdocs, jump to the
Development Environment Setup section for help installing
This section describes some notes on the dos and don'ts when writing documentation.
The headings and layout of the website, as well as other configuration settings, are managed from the mkdocs.yml file in the project root directory.
When writing documentation via a Markdown file, the following format has been followed:
- Text on a given line should not exceed 100 characters, unless it's example syntax or a link that should be broken up.
- Each new sentence should start on a new line. That way, if text needs to be inserted, whole paragraphs don't need to be adjusted.
- Links to other markdown files are relative to the file the link is placed in.
There are a set of well known governance files that are typically placed in the root directory
of most projects, like README.md, MAINTAINERS.md, CONTRIBUTING.md, etc.
mkdocs expects all files used in the static website to be located under a common directory,
docs/ for bpfman.
To reference the governance files from the static website, a directory (
created with a file for each governance file, the only contains
--8<-- and the file name.
This indicates to
mkdocs to pull the additional file from the project root directory.
For example: docs/governance/MEETINGS.md
NOTE: This works for the website generation, but if a Markdown file is viewed through Github (not the website), the link is broken. So these files should only be linked from
The file docs/developer-guide/api-spec.md documents the CRDs used in a Kubernetes deployment. The contents are auto-generated when PRs are pushed to Github. The script scripts/make-docs.sh manages the generation of this file.
On each PR pushed to https://github.com/bpfman/bpfman the documentation is generated.
To preview of the generated site, click on the
Details link of the
netlify/bpfman/deploy-preview Check from the Github GUI.
If you would like to test locally, build and preview the generated documentation,
from the bpfman root directory, use
mkdocs to build:
To preview from a build on a local machine, start the mkdocs dev-server with the command below,
then open up
http://127.0.0.1:8000/ in your browser, and you'll see the default home page
To preview from a build on a remote machine, start the mkdocs dev-server with the command below,
then open up
http://<ServerIP>:8000/ in your browser, and you'll see the default home page
Development Environment Setup
The recommended installation method is using
Once installed, ensure the
mkdocs is in your PATH: