Skip to content

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.json is copied by hand from openapi.public.json in the makimoto-api repository; 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.