doc-generation
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.
适合你，如果你是Axone合约开发者，需要保持文档与代码同步
npx oh-my-skill add axone-protocol/contracts/doc-generationcurl -fsSL https://oh-my-skill.com/install.sh | bash -s -- axone-protocol/contracts/doc-generationnpx oh-my-skill verify axone-protocol/contracts/doc-generation怎么用
商店整理自技能原文 · 版本 7a14fd6 · 表述以原文为准安装后，Claude 会指导你运行 `cargo make docs` 重新生成合约的 schema 和 Markdown 文档，并强调 Rust 类型和元数据是唯一来源，不要手动编辑文档。
当合约 API 或元数据变更、检查生成文档漂移、或准备文档提交时触发。具体包括修改 msg.rs、响应类型、文档注释、metadata.json、schema 生成代码或文档生成管道。
技能原文 SKILL.md
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/*.mdcontracts/*/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 docsis the preferred entrypoint; it already triggers schema generation.- The docs renderer uses
@fadroma/schema,jq,awk,perl, andprettierthroughMakefile.toml. - The generated docs reflect the semantics encoded in Rust doc comments. Fix the Rust comments first, then regenerate.