Contributing to the Documentation¶
Last updated: 2026-08-26
This covers the documentation site specifically. For contributing to Kawa, see CONTRIBUTING.md at the repository root.
Where Documentation Lives¶
| Section | Path | Authoritative repository |
|---|---|---|
| Home, Getting Started | docs/index.md, docs/getting-started.md |
This repository (kawa) |
| How It Works | docs/concepts/ |
This repository |
| Service (API, authentication) | docs/service/ |
This repository |
| SDKs | docs/sdks/<name>/ |
The corresponding SDK's own repository |
Service documentation, including the pipeline concepts and the API reference, is authored directly in this repository's docs/ directory, on main.
Change it the same way you'd change any other file here: a pull request against main.
SDK documentation is imported, not written here
If you're changing SDK-facing content, that change belongs in the SDK's own repository, not here. This repository only aggregates and displays it.
The Python SDK's docs come from makimoto-ai/makimoto-python, pinned to a release tag in .github/workflows/documentation.yml.
Currently, there is no automatic rebuild when the SDK repo changes: a new SDK release does not, by itself, update what's shown here.
To pick up SDK changes, a code owner must run the CI workflow manually via workflow_dispatch (which still rebuilds against whatever ref: is currently pinned, so the ref: bump has to happen first).
The API reference¶
Most of docs/service/api-reference.md is generated from docs/openapi.json at build time, by the hook in hooks/openapi_reference.py. A line openapi POST /v1/summarize on its own is replaced with that endpoint's heading, description, parameter, field and status code tables. The examples, limits and other guidance written by hand go under it.
- To change a generated table, change the spec, not the page.
docs/openapi.jsonis copied by hand fromopenapi.public.jsonin themakimoto-apirepository; descriptions belong there. - The build fails if a directive names an endpoint the spec doesn't have, and warns (failing CI) if the spec has an endpoint no page renders. After copying in a new spec, add a directive for any new endpoint.
Previewing locally¶
pip install -r docs/requirements.txt
mkdocs serve --no-strict
The Python SDK pages are imported only in CI builds, so locally they are
missing and MkDocs warns about them; --no-strict lets the rest of the site
preview anyway.
Open the URL it prints (typically http://127.0.0.1:8000/; the site serves
from the root because site_url in mkdocs.yml has no sub-path). The server
watches docs/, overrides/ and mkdocs.yml and reloads on save.
Previewing a pull request's changes¶
Every documentation pull request gets a comment from the bot with a link to
a downloadable preview build of that PR's site (a zip, expires after 14
days). This is not a live URL, GitHub Pages only serves one deployment for
this repository, and that one is reserved for main.
To view a preview: download and unzip it, then from inside that folder run a local static server, for example:
python -m http.server 8000
and open http://localhost:8000/ in your browser. Opening index.html
directly (via file://) won't navigate between pages correctly, MkDocs
generates directory-style URLs that only resolve through an actual server.
Diagnosing a failed documentation build¶
Both the PR check and the deploy step run:
mkdocs build --strict
--strict turns warnings, most commonly a broken internal link or a nav entry in mkdocs.yml pointing at a file that doesn't exist, into build failures. Reproduce it locally with the command above; the error message names the offending file and link.
Locally, the build will always report warnings about sdks/python/ pages, because those are imported only in CI (see Previewing locally). Ignore those and look for any other warning: that is the one failing the CI build.
A build that fails before that step (dependency install, YAML parsing) usually means a syntax error in mkdocs.yml or docs/requirements.txt; check the failed run's log under the repository's Actions tab for the exact step and error.
Review¶
Documentation pull requests go through the same review process as any other change to this repository; see CONTRIBUTING.md.