doc-generation

name	doc-generation
description	Guide for regenerating Axone contract schemas and rendered Markdown docs. Use when contract APIs or metadata change, when checking generated-doc drift, or when preparing documentation commits.
license	BSD-3-Clause
metadata	{"author":"axone.xyz","version":"1.0"}

Generated Documentation

Source of Truth

Generated docs come from Rust API types and schema metadata:

Rust messages/types + metadata.json
              ↓
      contracts/*/schema/*
              ↓
          docs/*.md

In this repository, the canonical command is:

cargo make docs

Do not treat docs/*.md as hand-edited source files. The Rust types and metadata are the source of truth.

What cargo make docs really does

cargo make docs already depends on:

• prerequisite checks (npx, awk, perl, jq)
• cargo make schema

That means one docs refresh can update both:

• contracts/*/schema/*
• docs/*.md

Standard Workflow

Regenerate everything

cargo make docs

Inspect what changed

git status --short
git diff -- docs contracts

Commit the generated artifacts

If the change is documentation generation only, prefer a message such as:

docs(gov): regenerate documentation
docs(vc): regenerate documentation
docs: regenerate generated documentation

Avoid vague subjects such as docs: update generated documentation.

When regeneration is required

Refresh generated docs whenever you change:

• message types in msg.rs
• response types exported in schemas
• doc comments that feed schema descriptions
• metadata.json
• schema generation code in src/bin/schema.rs
• the docs generation pipeline in Makefile.toml

File Expectations

After regeneration, review and commit all relevant generated artifacts:

• docs/*.md
• contracts/*/schema/*

Even if CI only reports drift on docs/*.md, schema files are still generated source artifacts in this repo and should stay in sync with the code.

Repo-Specific Notes

• cargo make docs is the preferred entrypoint; it already triggers schema generation.
• The docs renderer uses @fadroma/schema, jq, awk, perl, and prettier through Makefile.toml.
• The generated docs reflect the semantics encoded in Rust doc comments. Fix the Rust comments first, then regenerate.