Documentation¶
What every repository documents and where. The detailed writing rules, page templates and checks are in the
documentation style guide of ci-tools; this page sets what is required.
The site¶
- Every public code repository publishes a MkDocs site at
https://kokeb-labs.github.io/<repo>/, built with the shared theme packagekokeb-mkdocs-themeand thekokeb-docscommand-line tool (both inci-tools), versioned per tag, with the Doxygen API reference underapi/. - Pages live in
docs/, navigation indocs/.nav.yml(five tabs: Home, Get started, Concepts, Guides, Reference). The site configuration is_config/mkdocs.ymlwithdocs_dir: ../docs(ADR-0011); build withmkdocs build -f _config/mkdocs.yml --strict, and passmkdocs_config: _config/mkdocs.ymlanddoxygen_config: _config/Doxyfileto the docs workflow. kokeb-docs checkruns the same checks locally as the docs workflow.- The build is strict: broken links, pages missing from the nav, figures or generated regions that no longer match the code, and snippets that do not compile all fail CI.
Page sets¶
| Kind | Required pages |
|---|---|
| Driver | Home, Quickstart (starting with the host example), Installation (CMake first, then ESP-IDF), Platforms, Hardware, Architecture, Contract, API guide, API reference, Examples, Porting (with Editor setup), Configuration (if it has a Config or Kconfig), Testing and CI, Troubleshooting, Changelog, Figures |
| Standalone library | Home, Quickstart (starting with the host example), Concepts, Contract, API guide (one page per utility for a collection), API reference, Integration, Platforms, Testing and CI, Changelog |
| kb-core | Home, Quickstart, Architecture (the four parts and their direction), Contract, one section per part (utils, rtos, interfaces, handlers), Handler model, one page per handler, Build options and MCU gate, Release trains and compatibility, Threading, Host build, API reference, Testing, Changelog |
kb-hal-common and board HALs |
Home with the board card, Quickstart, Hardware (block diagram, pin table, connectors, power), Architecture (managers, start-up order), Contract, one guide page per board function, API reference, Examples, Bring-up and troubleshooting, Changelog |
| Product | Home, Getting started, Architecture (tasks, data flow), Operation (modes, commands, configuration, the fault catalogue), Hardware (links the HAL site), Development, Troubleshooting, Changelog, ADRs |
| CI and tools | Home, Quickstart, one page per workflow or script, Versioning, Migration guides, Changelog |
What each page contains is in the style guide's standard page sets.
The Contract page¶
Every driver, library, kb-core, HAL and product has docs/contract.md, under Concepts right after
Architecture. It is the short, normative summary of what the repository promises, in this order:
# Contract
What <repo> promises, what it needs, and the rules a caller follows.
## Promises
- One bullet per guarantee a caller can rely on.
## Depends on
| Dependency | Version | Why |
| --- | --- | --- |
## Threading
Which objects are thread-safe, which locks they take, what may run in an ISR.
## Errors
The error type, every value a caller can see, and what it means. For a handler or HAL, the `kb::Status` mapping.
## Memory
Allocation (none after start-up), static buffers and their sizes, stack needs of callbacks.
## Platform
What is platform-free and what is not. MCU-bound drivers say so here and name the families and the peripheral.
## Deviations from the standard
Each rule of the Kokeb Labs standard this repository does not meet yet, with its issue.
The Contract page links the standard for the rules it inherits rather than restating them, and states only what is specific to the repository.
Doxygen¶
The API reference is generated from the public headers with the shared settings in ci-tools. Each repository
keeps its Doxyfile in _config/Doxyfile and runs Doxygen from the root (doxygen _config/Doxyfile), so the paths
inside are relative to the root:
| Setting | Value | Why |
|---|---|---|
INPUT |
inc/ (drivers), the public header folders (libraries, kb-core, HALs) |
Only the public API |
EXTRACT_ALL |
NO |
Undocumented symbols show up as warnings instead of empty entries |
EXTRACT_PRIVATE |
NO |
Private members are not API |
WARN_IF_UNDOCUMENTED |
YES |
|
WARN_NO_PARAMDOC |
YES |
Every parameter is documented, with its unit |
WARN_AS_ERROR |
FAIL_ON_WARNINGS |
CI fails on any warning in the public headers |
USE_MDFILE_AS_MAINPAGE |
docs/_doxygen/mainpage.md |
|
GENERATE_HTML |
YES, merged into the site under api/ |
Each public symbol has a brief description; each function documents its parameters with units, its return value and the error values it can return, and whether it does I/O or blocks.
README¶
The README is the front door: someone who reads only it knows what the part is, whether the driver fits their project, where the datasheet is, and how to get to a first reading. The reference stays on the site. Sections, in this order, only those that apply:
# Nameand a one-sentence hero line: what it is and does.- Badges that are true: the main test workflow, license, C++ standard, latest release (once one exists).
- The documentation link in bold.
- One short paragraph in plain words: what the part does and what the driver gives you.
- One layer or block figure.
- At a glance: a two-column table: the part (vendor, package, supply), what it measures or does, the bus, what else it drives, the driver's properties, where it runs, and its status (version, and "not yet verified on hardware" until it is).
- Datasheet (drivers): the generated card (
<!-- generated: datasheet-card -->): document, revision, where to get it, and the link to the Datasheet map. - Try it on your PC: the host example in one command.
- Use it on your MCU: 1. a minimal wiring table, 2. one line on the port with a link to Porting, 3. the generated
quickstart region (
<!-- generated: quickstart-code -->), which checks every return value, and one line on how the driver starts (EnsureInitialized()). - What it does: five to seven bullets.
- Install: the submodule line and the CMake lines.
- Documentation: a table of the pages with a "Read it when you want to" column. Links go to the pages in the
repository (
docs/<page>.md) while the site is not published, to/latest/once it is. - Tests and quality: one command line, and one sentence on what CI checks.
- License: one line (MIT, or CERN-OHL-P-2.0 for a hardware design).
The datasheet trail¶
A driver lists the vendor documents it was written against in docs/datasheets.yml
(ADR-0019), and, for each thing it takes from them, a topic: the datasheet's own
section name and printed page, the driver API that implements it, and the docs pages that explain it. The
datasheet generator (shipped in the template, tools/docs/generators/datasheet.py) builds three regions from it,
so a revision or a page number is written once:
datasheet-cardon the README, the home page and Hardware: document, revision, date, where to get it;datasheet-mapondocs/datasheet.md: every topic with section, page, driver API and docs page;datasheet-refsat the top of each page a topic names: a collapsed box listing the sections that page relies on.
Page numbers link into the PDF (#page=N) when the vendor publishes a stable PDF URL (pdf, with page_offset when
the printed and PDF page numbers differ). The repository never contains the PDF.
A driver's README names the chip and the part, not the org: the driver is usable on its own (ADR-0012).
No table of contents, no emoji walls, no check-mark feature lists, no badges that link nowhere, no duplicated API tables.
Code on the site¶
- Every C++ block on the site compiles: it lives in
tests/docs/and is pulled into the page as a generated region, so a change that breaks an example fails CI. - Examples check every
ResultandStatus. An example that ignores a return value teaches the wrong thing. - Figures are generated (
kokeb-docs figures) with light and dark variants and alt text.
Changelog and decisions¶
docs/changelog.mdincludesCHANGELOG.md(release.md).- Decisions that affect more than one repository are ADRs here, in
adr/. Decisions local to one repository are ADRs in its owndocs/adr/, in the same format.