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.

Current topics and their extraction projects

Topic

Source area

XML project

Wireless networking

sys/net80211

net80211

Virtual memory

sys/vm

vm

Scheduling

sys/kern/sched_*.c and shared kernel interfaces

kern

Virtual file system

sys/kern/vfs_*.c and shared kernel interfaces

kern

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.