Building and extending this manual¶
Dependencies¶
The Python dependencies are listed in Documentation/sphinx/requirements.txt:
Sphinx builds the manual, Breathe renders Doxygen XML, and Furo supplies the HTML
theme. Doxygen and awk are separate system dependencies. On FreeBSD, install
devel/doxygen and a supported Python 3; awk is part of the base system.
HTML builds do not require TeX or Graphviz.
From the source root, create an isolated Python environment and build:
python3 -m venv Documentation/.venv
. Documentation/.venv/bin/activate
python -m pip install -r Documentation/sphinx/requirements.txt
make -C Documentation html
Open Documentation/_build/html/index.html. Generated documentation and
virtual environments are excluded from the Sphinx source tree and ignored by
Git. The requirements list direct dependencies, rather than freezing all
transitive packages. The initial build was checked with Sphinx 9.2.0,
Breathe 5.1.0, Furo 2025.12.19, and Doxygen 1.18.0.
To treat Sphinx warnings as build failures:
make -C Documentation html SPHINXOPTS="-W --keep-going"
SPHINXBUILD selects the Sphinx executable, and BUILDDIR changes the output
directory. make -C Documentation help lists output formats. PDF output is
produced by Sphinx’s latexpdf target and additionally requires a TeX
installation.
Subsystem projects and API extraction¶
Each Doxyfile-NAME in tools/kerneldoc/subsys is a separate XML project.
Sphinx discovers that catalog and registers all project names in
breathe_projects. There is no default Breathe project: every extraction
directive must specify :project: NAME. Registering a project does not
extract its XML or publish every symbol in the manual.
The build has two separate stages: BSD make extracts XML, then Sphinx renders
one manual from the authored RST pages and those XML projects. The local build
selection is listed in Documentation/sphinx/subsystems, one project per line.
The existing make dependency graph in tools/kerneldoc/subsys/Dependencies
orders projects that use each other’s tag files and generates KObj headers.
There is no manually ordered dependency list in the Sphinx configuration.
To list the catalog or select additional extraction projects:
make -C Documentation list-subsystems
make -C Documentation xml SUBSYSTEMS="net80211 libkern"
make -C Documentation html SUBSYSTEMS="net80211 libkern"
Use SUBSYSTEMS=all to extract every catalog project, for example in CI.
That can be substantially more expensive than extracting the projects used by
this manual. Selecting a subset does not remove previously generated XML.
Adding a project to the extraction selection does not create reference pages;
those pages must explicitly import its declarations.
xml invokes the subsystem BSD make framework and writes raw XML and tag
files under _build/doxygen. html and the other output targets depend on
xml. DOXYGEN_XML_ROOT changes the extraction/output root. To consume
prebuilt XML without running Doxygen, use:
make -C Documentation render-html DOXYGEN_XML_ROOT=/path/to/xml/root
The root contains one NAME/xml/index.xml per extracted subsystem. A direct
sphinx-build invocation also consumes existing XML without extraction.
Missing XML for a project requested by a reference directive is a build error.
make doxygen from the source root remains available on FreeBSD to extract
all subsystem projects separately.
The rendering extension prepares XML copies under _build/doctrees/breathe
and normalizes function-pointer declarations for Breathe while preserving
return-type references. Raw XML is not modified. Unchanged copies are reused
so incremental Sphinx builds can retain their dependency timestamps.
DOXYGEN and AWK select the extractor and header generator executables.
BSDMAKE selects BSD make; the base make is used on FreeBSD and bmake
is needed on other hosts. PYTHON selects the build helper’s interpreter.
TARGET_ARCH selects the Doxygen preprocessing architecture, defaulting to
the host architecture mapped to FreeBSD naming conventions. An extraction
represents one configuration, not every architecture/kernel option combination.
Topics and canonical reference pages¶
Sidebar categories are captions on hidden root toctree directives.
The front page introduces only the top-level topics; the sidebar retains
nested guide and API navigation. A reading topic and a Doxygen extraction
project are independent. Several topics can publish different interfaces
from one project without generating its XML twice.
Topic |
Source area |
XML project |
|---|---|---|
Wireless networking |
|
|
Virtual memory |
|
|
Scheduling |
|
|
Virtual file system |
|
|
Each topic has a kernel/TOPIC/index.rst, narrative guides, and an API
reference index with canonical per-header or per-group pages. Scheduling
uses implementation-specific API pages as well. The kern configuration
also includes public scheduler and VFS declarations from sys/sys so
function lookup can use their header declarations.
To add a topic, create its index and guides, link the index from the root
Kernel toctree, and add a short topic description to the front page.
Its Breathe directives select the owning extraction project explicitly.
Add that project to sphinx/subsystems once, even if several topics use it.
Only a new extraction project needs a new Doxyfile-NAME and any associated
make dependencies. Sphinx discovers that configuration automatically.
A reference page can import a header, a conceptual Doxygen group, or selected functions. Each extraction directive chooses its XML project explicitly:
.. doxygenfile:: example.h
:project: subsystem-name
.. doxygengroup:: ExampleGroup
:project: subsystem-name
.. doxygenfunction:: example_function
:project: subsystem-name
These are alternative ways to publish symbols. Give each symbol one canonical reference location; importing the same declaration through several headers, groups, or projects can create duplicate targets. For an interface shared by subsystems, its owning subsystem publishes it and other topics reference it. Per-header or per-group pages keep reference pages and navigation manageable.
Links and declaration excerpts¶
Use :doc: for document links, :ref: with explicit labels for section
links, and C-domain roles for inline API links, including links across projects:
Driver setup calls :c:func:`ieee80211_ifattach`.
An inline reference links to an already published declaration. A Breathe
doxygenfunction directive imports a declaration and its documentation from
XML. Its :outline: option imports only the declaration, which is useful
when that page is the canonical synopsis for the symbol.
To display a declaration already published on a reference page, use the C alias directive. It reuses the imported signature and links to its canonical location:
.. c:alias:: ieee80211_ifattach
Breathe’s :no-link: suppresses its target generation, but with the current
Sphinx C domain it does not prevent warnings about duplicate declarations.
Use c:alias for repeated signatures rather than importing a symbol twice.
Project selection and symbol scopes are separate: :project: NAME selects
XML, but does not prefix the Sphinx C-domain name with NAME. Keep unique
exported kernel symbols in the shared C domain. For file-private helpers
whose names repeat, use a documentation scope containing the subsystem and
source file, consistently on their reference pages:
.. c:namespace:: dev_example.example_c
.. doxygenfile:: example.c
:project: dev_example
.. c:namespace:: NULL
A cross-project link to a scoped helper uses its qualified documentation name,
for example :c:func:`dev_example.example_c.attach`.
Function lookup with doxygenfunction still requires a name unique within
the selected XML project; use appropriately scoped file pages for ambiguous
file-private functions. Namespace selection does not disambiguate XML lookup.