Files
solidcraft/docs/book/src/dev/command-guides.md
T
Victor Santos Oliveira 91638cb1f3 Add practical command guides and a contribution template (#5237) (#6772)
* claim: #5237 command-level guide follow-up

* docs: add practical command guides and resource contributions (#5237)

* docs: index practical guides and reject incomplete command links
2026-10-26 12:24:23 +00:00

3.4 KiB

Contributing command guides and resources

The command reference combines the live command registry with reviewed Markdown guides. A guide appears inside its command's entry, before the collapsed automation syntax. You can improve one entry without rewriting the whole manual. The reference's Practical guides list automatically links to every available guide; adding a guide does not require editing an index or Rust code.

Add or improve an entry

  1. Find the command in the reference. Its ID is in Automation details.
  2. Copy the guide template to docs/book/command-guides/<command-id>.md, or edit its existing file. For example, Extrude lives in solid.extrude.md.
  3. Explain what the tool does, what must exist or be selected first, the dialog's choices in a table, a short example, and useful DOs and DON'Ts. Use plain language rather than copying the raw automation parameters.
  4. Add related commands and any checked community resources, then open a pull request. Documentation changes are reviewed like code.

Do not edit the generated src/reference/commands.md: rebuilding replaces it. The generator rejects guide filenames whose command is absent from the registry. Names, groups, shortcuts and automation parameters continue to come from that registry; handwritten explanations remain editable independently.

Use fourth-level headings (####) inside an entry so the command remains the parent section. Write image and page paths relative to the generated reference page, docs/book/src/reference/commands.md, not to the input guide file. For example, ../generated/sheet-metal.png and ../guide/sheet-metal.md.

Write a command link as {{#command sheet.hem}}. The generator inserts its current name and links directly to that command. Unknown or missing command IDs and unfinished directives fail the book build, helping contributors catch stale links. Normal Markdown links can point to guide pages or external resources.

Community resources

You can add a focused tip, a short demo, a model or an illustrative screenshot to the entry's resource table. Explain what the reader learns from each link; include author and licence information. Links are reviewed, not automatically collected from the web. A resource need not cover the whole command.

Use original SolidCraft examples or openly licensed resources with permission to share. Do not use designs, screenshots, help text or artwork extracted from commercial CAD products, or GPL/LGPL/AGPL code. Prefer small public-safe examples and remove private designs, paths and account information from evidence.

For a new file asset, follow assets/AGENTS.md and add its attribution in a new attribution/pending/<change>.md file. A reproducible recipe in docs/book/scripts/ can be rendered by the book builder; generated images stay out of Git. Existing examples demonstrate both inline pictures and resource links.

Preview and review

Run cargo xtask book with mdBook installed, inspect the command entry and its links, and check the example in SolidCraft. Confirm the required selection, units, defaults and limitations against the implementation. Show reviewers an actual before/after screenshot of the rendered entry. Repository quality gates still apply before a commit.

Copyable template

{{#include ../../command-guide-template.md}}