Updating the rendering manual

Quarterly updates should regenerate source references and then review changed contracts. Regeneration relocates links and inventories; it does not rewrite or verify architectural explanations.

Source of truth

The section keeps one rendering_snapshot.json with the source revision, engine version, narrative review revision, and review date. rendering_source_anchors.json names important files and symbol locators. The reference directory is generated by tools/rendering_docs.py.

Narrative pages cite the generated source maps, so revision hashes and line numbers do not need editing throughout the prose. Diagrams remain authored source beside the pages that use them.

Refresh references

From the documentation repository, run:

python3 tools/rendering_docs.py refresh --engine /path/to/redot-engine --revision master

The tool reads committed source from the requested local revision. It rebuilds the class/header indexes, source symbol links, marker catalog, consumer search indexes, and machine-readable inventory. Missing source locators stop the refresh so a removed symbol cannot silently produce an unrelated link.

A refresh preserves the previous narrative-review revision and date. If it differs from the new source revision, the baseline page displays that the prose still needs review. An updated source index is not a completed update.

Review changed contracts

Compare the old and new source revisions, including integration files outside the primary rendering directories. Use the inventory and source-anchor list to locate those consumers. Review:

• Construction, destruction, global access, and ownership changes.
• Thread/queue behavior, loading progress, and GPU completion.
• Pass order, buffer requirements, new callbacks, and capability limits.
• Shader representations, uniform layouts, caches, and native conversion.
• Driver/platform support, fallbacks, and imported resource contracts.
• New, removed, or resolved TODOs and previously assessed proposals.

Update prose, diagrams, and assessed observations together. A resolved marker should leave the unfinished-path assessment; a proposal that became implemented behavior belongs in the architecture explanation. Avoid carrying speculative performance claims forward without measurements.

Record the review

After reviewing the narrative against the refreshed source, record the date:

python3 tools/rendering_docs.py review --engine /path/to/redot-engine --date YYYY-MM-DD
python3 tools/rendering_docs.py check --engine /path/to/redot-engine

The check command verifies generated content against the recorded committed revision and validates source locators. It does not assert that prose or diagrams match code. It also does not require the engine checkout to remain at that revision once the Git objects are available.

Validate the site

Run dotnet test from the documentation repository. The documentation link audit renders configured versions, checks internal pages/headings, and rejects invalid Mermaid embeds. Inspect the running site too: diagrams must remain readable, tables must fit or scroll, and the reading order must work.

For a release snapshot, copy the section's narrative, JSON metadata, reference pages, and diagrams together into the version's documentation. Keep the old snapshot's source revision intact. The current refresh tool targets latest; archived version content is preserved rather than regenerated by that tool.