Shutong Wu
44fb09bd68
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
43 lines
1.4 KiB
Bash
Executable File
43 lines
1.4 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Pre-commit hook: regenerate the Docusaurus tool/resource reference when
|
|
# any tool/resource module is part of the commit. Installed by
|
|
# tools/install-hooks.sh; opt-in (devs without the hook see no behavior change).
|
|
# To bypass for a single commit: git commit --no-verify
|
|
|
|
set -e
|
|
|
|
REPO_ROOT="$(git rev-parse --show-toplevel)"
|
|
GENERATOR="${REPO_ROOT}/tools/generate_docs_reference.py"
|
|
|
|
if [[ ! -f "$GENERATOR" ]]; then
|
|
echo "pre-commit: $GENERATOR missing; skipping docs regeneration." >&2
|
|
exit 0
|
|
fi
|
|
|
|
relevant_paths='^Server/src/services/(tools|resources|registry)/'
|
|
|
|
# Look at the staged change set only — exclude pure deletions.
|
|
staged=$(git diff --cached --name-only --diff-filter=ACMR)
|
|
|
|
if ! grep -qE "$relevant_paths" <<<"$staged"; then
|
|
exit 0
|
|
fi
|
|
|
|
echo "pre-commit: tool/resource module changes detected — regenerating /website/docs/reference/"
|
|
|
|
# Prefer uv if available (matches how the Server's deps are pinned). Fall back
|
|
# to system python — the generator handles its own sys.path setup.
|
|
if command -v uv >/dev/null 2>&1 && [[ -f "${REPO_ROOT}/Server/pyproject.toml" ]]; then
|
|
(cd "${REPO_ROOT}/Server" && uv run python "$GENERATOR")
|
|
else
|
|
python3 "$GENERATOR"
|
|
fi
|
|
|
|
# Stage any reference files that changed so the commit captures them.
|
|
if ! git diff --quiet -- "website/docs/reference"; then
|
|
echo "pre-commit: staging regenerated reference pages."
|
|
git add website/docs/reference
|
|
fi
|
|
|
|
exit 0
|