---
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:

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

In this repository, the canonical command is:

```bash
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

```bash
cargo make docs
```

### Inspect what changed

```bash
git status --short
git diff -- docs contracts
```

### Commit the generated artifacts

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

```text
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.