Contributing to these docs¶

This page explains how to edit the trustmint developer/integrator docs (docs/dev/) and, importantly, what must not be hand-edited here because it is generated upstream.

Where the source lives¶

The source lives in the trustmint repo under docs/dev/. It is the dev audience of trustmint’s multi-audience Sphinx model (docs/dev/ for integrators, plus separate help/ end-user and insider/ ops audiences). Each audience is a self-contained Sphinx project with its own conf.py that imports the shared Carbon theme + conf_base from docs/_shared/ at build time. Do not edit conf.py — it wires the shared theme.

Authoring rules¶

MyST Markdown only. Write pages as .md using MyST (myst_parser). Directives use the colon-fence (:::{note}) or backtick-fence (```{toctree}) form. Convert any legacy RST source to MyST when you migrate it.
Add a page by creating docs/dev/<name>.md (or under a subdir like protocol/, concepts/, design/, adr/) and adding it to a {toctree} in docs/dev/index.md. The toctrees in index.md are the master order.
Diagrams ship as a paired source + render: a mermaid .mmd source and a rendered .svg under docs/dev/_static/diagrams/. Commit both. Regenerate the SVG with the repo mermaid pattern:
```
mmdc -i docs/dev/_static/diagrams/<name>.mmd \
     -o docs/dev/_static/diagrams/<name>.svg \
     -c docs/_static/diagrams/mermaid-config.json
```

Build the site¶

The site is built with sphinx-build -b dirhtml. Build locally and confirm it succeeds before opening a PR. Toctree entries that point at pages not yet authored emit warnings, not errors.

Do NOT hand-fork generated content¶

Some content is generated upstream and rendered or linked here. Editing the rendered copy by hand creates silent drift from the source of truth and is prohibited:

Content	Source of truth (do not hand-edit in `docs/dev/`)	Generator
OpenAPI reference	`services/thingmake/docs/openapi/thingmake-openapi.{yaml,json}`	`cmd/openapi-snapshot-gen`
Error catalog	`services/thingmake/docs/errors/thingmake-error-catalog.{md,json}`	`cmd/error-catalog-gen`
SDK quickstarts	`services/thingmake/sdks/{go,python}/` + `sdks/README.md`	generated SDKs
Conformance usage	`conformance/services/thingmake/`	conformance suite

When the upstream artifact changes, regenerate it at the source and let the docs re-render — never copy operation definitions, error codes, or SDK snippets into a page. The API reference renders the OpenAPI YAML via the {openapi} directive (plus a raw-spec download link) precisely so these docs stay a faithful view of the generated spec.