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. .. list-table:: Current topics and their extraction projects :header-rows: 1 :widths: 25 50 25 * - 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. 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.