Generated by tools/generate_docs_reference.py; the "Check docs reference is
fresh" CI job flagged testing/run_tests.md as stale after clear_stuck was added.
PR #1157 review (Copilot + CodeRabbit) flagged that several tool pages
had truncated frontmatter, e.g. manage_asset rendering as:
description: "Performs asset operations (import, create, modify, delete, etc"
Root cause: the generator used `description.split(".")[0]` to derive the
frontmatter blurb. That cuts at the FIRST period — including periods
inside abbreviations and parenthesized lists ("etc.) in Unity."), so
the rendered description stopped mid-clause.
Fix: introduce `_first_sentence()` that splits on real sentence
boundaries — `.` / `!` / `?` followed by whitespace + capital, or a
paragraph break — and falls back to the whole string if no boundary
exists. Also caps absurdly long single-sentence descriptions at ~240
chars to keep frontmatter compact.
All three call sites that used the old split:
- frontmatter `description:` in render_tool_page
- group-index bullets in render_group_index
- catalog-index bullets in render_catalog_index
Regenerated all 43 tool pages + 9 group landings + catalog index +
resources catalog. Verified `--check` passes round-trip and full
website build is clean.
manage_asset now reads: "Performs asset operations (import, create,
modify, delete, etc.) in Unity."
Hand-written examples on five high-traffic tool pages (preserved across
regeneration by the generator) and a proper nested Tools sidebar so
groups are collapsible categories instead of a flat list.
Examples (in <!-- examples:start --><!-- examples:end --> blocks):
- manage_gameobject: create primitives, modify (move + reparent),
delete by tag, duplicate, multi-instance routing
- manage_scene: load, paged get_hierarchy, save, create from template,
additive multi-scene editing
- manage_material: create, assign to renderer, set_material_shader_property,
tint via MaterialPropertyBlock (mode: property_block) for batching
- manage_script: REWRITTEN to match the tool's actual surface
(create / read / delete only). The previous draft conflated it with
script_apply_edits / validate_script — those examples moved to:
- script_apply_edits: replace_method, insert_method (with position
anchor), delete_method, anchor_insert (regex anchor), multi-op
atomic transaction
- batch_execute: 9-op spawn-three-colored-cubes payload, parallel/
fail_fast semantics, batch-size limits
Generator fixes (tools/generate_docs_reference.py):
- Examples-preservation regex now requires markers at line boundaries
(re.MULTILINE + ^/$ anchors). Previously the generator's own warning
banner referenced the literal `<!-- examples:start --><!-- examples:end -->`
strings and the lazy regex matched THOSE first — capturing empty
content and overwriting real examples with the placeholder
- --check mode now reads existing examples from the committed location
(passes `examples_source=TOOLS_OUT`) instead of the empty tempdir,
so CI drift detection no longer false-positives every run
- Emits `_category_.json` per group dir + a sidebar_class_name on the
catalog index — Docusaurus then renders Tools → group → tool as a
proper nested tree, with the duplicate catalog-as-child entry
CSS-hidden via .sidebar-hidden
Sidebar (sidebars.js):
- Reference > Tools is now a single category, link points to the
catalog index, items autogenerate from website/docs/reference/tools/
using the new `_category_.json` metadata for nesting
Verified: build clean, generator --check exits 0, examples survive
end-to-end regeneration round-trip.
Typography upgrade matching modern AI-product docs sites (e.g. benchflow):
- Satoshi (Fontshare, weights 300/400/500/700/900) for body and headings
- JetBrains Mono (Google Fonts, 400/500/700) for monospace
- Loaded via stylesheet links + preconnect hints in docusaurus.config.js
- custom.css updates: --ifm-font-family-base, --ifm-font-family-monospace,
tighter heading letter-spacing, slightly bumped line-height for Satoshi,
brand color shifted to indigo (#4f46e5) to pair with the new sans
- Inline code nudged 0.88em to sit on Satoshi's baseline
Emojis removed across all in-house content for a cleaner, professional
tone:
- generator banner: dropped the gear glyph
- generator parameter table: required column is now "yes" / "—" instead
of an emoji checkbox (regenerated all 43 tool pages)
- install.md: status-text instead of green-dot emoji
- SECURITY.md: Yes / No instead of check/cross
- ISSUE_TEMPLATE/config.yml: plain link labels, no leading emoji
Verified:
- npm run build succeeds (5.7s client, 4.5s server)
- generator --check exits 0 (deterministic regeneration)
- HTML head includes both font stylesheets + preconnect hints
- CSS bundle resolves Satoshi and JetBrains Mono font-family stacks
Introduces tools/generate_docs_reference.py — the single Python script
that emits every reference page under website/docs/reference/ from the
live @mcp_for_unity_tool and @mcp_for_unity_resource registries.
What lands:
- tools/generate_docs_reference.py: introspects function signatures
(Annotated[Type, "description"]), preserves hand-authored examples
between <!-- examples:start --><!-- examples:end --> markers, supports
--write (default) and --check (CI drift detection) modes.
- tools/hooks/pre-commit: installed via tools/install-hooks.sh; when a
staged change touches Server/src/services/{tools,resources,registry},
regenerates the reference and re-stages it. Contributors don't have
to remember.
- .github/workflows/docs-generate.yml: runs --check on every PR and on
pushes to beta. Fails with a one-line fix command if the committed
reference drifts from the registry. Also runs a count sanity check
(#decorators must equal #generated md files).
- website/docs/reference/: 43 tool pages across 9 groups (animation,
core, docs, probuilder, profiling, scripting_ext, testing, ui, vfx)
+ group landing pages + 25-resource catalog. Sidebar wired with
Docusaurus's autogenerated mode so new tools appear automatically.
- README.md: "Available Tools" / "Available Resources" lists retired —
these were drifting on every release. Replaced with a single link to
the generated reference. (Root README slim is M5.)
Source of truth: Python. The C# attributes carry only Name/Group/
Description; the Python @decorator owns the richest typing via
Annotated[...], which is what MCP clients actually see over the wire.
Tested:
- generator runs clean (43 tools, 9 groups, 25 resources, deterministic)
- --check exits 0 against committed output
- pre-commit hook installs via existing tools/install-hooks.sh path
Shutong Wu