Claude/reorganize api docs acr tb#481
Merged
Merged
Conversation
Reorganize the `docs/` tree so every artifact lives in a subfolder keyed
to its type, with a master index one level up that links to every
category and every entry:
docs/
├── README.md Master categorized index (rewritten)
├── architecture/ Dependency matrix, extension policies (existing)
├── specs/ Wire/asset/plugin ABI formats (existing)
├── plans/ Roadmap + milestones (add FEATURE_ROADMAP.md)
├── status/ Project status snapshots (new, holds PROJECT_STATUS.md)
├── guides/ User-facing guides (new, holds packaging.md)
├── tooling/ Doc generators + Doxygen setup (new)
├── api/ Auto-generated API pages (gitignored)
├── screenshots/ Images (existing)
└── wine-upstream/ Wine patches (existing)
Fix API-doc links across the repo to match the new layout:
- README.md references docs/plans/, docs/status/, docs/guides/ paths
and points at the wiki's API-Reference as the API entry point.
- wiki/_Sidebar.md replaces the misnamed "API Docs (Doxygen)" link
with Documentation Index + Doc Tooling links.
- wiki/Home.md adds [API Reference](API-Reference) alongside the
Documentation Index link.
- wiki/Build-System-and-CMake-Modules.md and
docs/plans/tier3-polish-maturity-milestone.md use the new paths.
Generator (docs/generate-api-docs.sh) improvements:
- Generated index now links back to the master docs index and to the
sibling Component/System quick references.
- Per-header pages include back-links to the API index and master.
- Top-level overview files (ComponentIndex, SystemIndex) are grouped
under an "Overview" heading instead of becoming their own sections.
- Free-function filter no longer drops any line containing `::`, which
regressed indexing of valid free functions with namespace-qualified
return types (e.g. `std::unique_ptr<X> MakeLinearTree(`). Now only
rejects when the matched function name is itself preceded by `::`.
Recovers 177 previously-skipped symbols (16799 → 16976 total).
https://claude.ai/code/session_01TuKSsMgreD8WhdcLqhT8E4
Move every wiki page — except Home.md, _Sidebar.md, and _Template.md
— into a category subfolder keyed to its _Sidebar section:
wiki/
├── Home.md, _Sidebar.md, _Template.md (root, GitHub wiki convention)
├── getting-started/ 13 pages (tutorials, intro, architecture)
├── subsystems/ 34 pages (engine subsystems)
├── gameplay-tools/ 30 pages (gameplay, editor, asset tooling)
├── platform/ 5 pages (platform support)
├── graphics/ 23 pages (rendering/graphics)
├── advanced/ 19 pages (perf, memory, testing, code health)
├── specifications/ 3 pages (wire formats, plugin ABI)
└── reference/ 8 pages (auto-generated symbol/file indexes)
Link maintenance:
- 948 internal wiki links in 110 pages rewritten to relative subfolder
paths (Python script, `.md`-suffix preserved for explicitness).
- _Sidebar.md entries updated to subfolder paths.
- docs/README.md master index updated — 142 `../wiki/PageName.md` links
now point at `../wiki/<category>/PageName.md`.
- Relative paths in moved pages (images, source files, ../docs/ refs)
gained an extra `../` hop to account for the deeper location.
- README.md, CLAUDE.md, and docs/tooling/README.md external references
updated.
Generator updates (new output locations):
- generate-symbol-index.sh → wiki/reference/{Symbol,Function,Class,Enum,Macro}-Index.md
- generate-file-tree.sh → wiki/reference/File-Tree.md
- generate-class-hierarchy.sh → wiki/reference/Class-Hierarchy.md
- generate-flowchart.sh → wiki/getting-started/Engine-Architecture-Flowchart.md
- update-codebase-stats.sh → wiki/advanced/Codebase-Statistics.md
- Source-link prefix bumped from `../<path>` to `../../<path>` in the
reference indexes so they still resolve after the extra nesting
(35,000+ backlinks updated).
Script updates (subfolder-aware):
- sync-wiki.sh: Entity-Component-System, Testing, SparkEditor, Home
page paths updated; check-mode snapshot/restore now handles the
whole tree instead of only wiki-root `.md`.
- check-wiki-nav.sh: extracts sidebar link basenames (slugs) and
recurses into subfolders for the actual-pages set.
- check-wiki-quality.sh: Contributing.md and Testing.md paths moved
to advanced/.
Verified with:
- tools/check-wiki-nav.sh : consistent (135 pages, all in sidebar)
- tools/check-wiki-quality.sh : passed
- docs/update-all-docs.sh check: all 9 generators report up to date
Pre-existing broken links (14 references to pages that never existed —
`Scripting-System.md`, `Editor-Panels.md`, `VR-System.md`, etc.) are
unchanged; they were dead before the move and remain dead after. Left
for a future cleanup pass.
https://claude.ai/code/session_01TuKSsMgreD8WhdcLqhT8E4
Deep-scanned every .md under the repo for broken markdown links and
fixed every one. Zero broken file or bare-slug links remain across
37,144 checked references.
New pages (covering substantial real subsystems / workflows that were
referenced but had no target):
wiki/subsystems/Event-Response-System.md
— 1146-LOC data-driven "When/If/Then" rule engine with editor
panel and 15-case test suite. Added to _Sidebar.md under Engine
Subsystems and to docs/README.md master index.
.claude/knowledge/git-rebase-conflicts.md
— Per-file-type resolution rules for rebase conflicts (AUTO:
sections, stat counters, source code).
.claude/knowledge/github-api-pr-checks.md
— Full PR-check polling / diagnosis / rerun workflow via gh.
.claude/knowledge/clang-format.md
— CI-matching clang-format invocation; documents why `head -50`
must never appear in the pre-commit check.
Redirected 31 broken link references to the existing page that already
covers the topic:
Editor-Panels, Editor-Architecture, Scene-Hierarchy, Inspector-Panel,
Asset-Browser → gameplay-tools/SparkEditor.md
Scripting-System → subsystems/Scripting-with-AngelScript.md
ECS-Architecture, ECS-and-Components → subsystems/Entity-Component-System.md
Build-System → advanced/Build-System-and-CMake-Modules.md
Localization-System → subsystems/Localization.md
VR-System → platform/VR-Support.md
Physics-System → subsystems/Physics.md
Cinematic-System → gameplay-tools/Cinematic-Sequencer.md
Graphics-Engine → subsystems/Rendering-and-Graphics.md
Screen-Capture → gameplay-tools/Movie-Render-Pipeline.md
Console-System, Console → gameplay-tools/SparkConsole.md
Profiler → advanced/Profiler-and-Debugging.md
Seamless-Area-Streaming,
World-Origin-System → subsystems/Large-World-Support.md
Networking-System → subsystems/Networking.md
Quality-Presets → advanced/Configuration-Reference.md
Other fixes:
.claude/README.md: renamed placeholder `filename.md` inside a fenced
code-block example to `other-entry-filename.md` (no functional
change; the scanner formerly flagged the sample syntax).
Verified with:
tools/check-wiki-nav.sh : consistent (136 pages, all in sidebar)
tools/check-wiki-quality.sh : passed
docs/update-all-docs.sh : all 9 generators report up to date
scan-all-links (tmp) : 37144 checked, 0 broken
https://claude.ai/code/session_01TuKSsMgreD8WhdcLqhT8E4
Deep scan of the codebase turned up five substantial topics with
significant committed source but no dedicated wiki coverage:
wiki/graphics/D3D11-Backend.md Primary Windows backend (~360 LOC)
wiki/graphics/Vulkan-Backend.md Largest cross-platform backend (~680 LOC)
wiki/graphics/OpenGL-Backend.md 4.6 core fallback backend (~450 LOC)
wiki/graphics/Metal-Backend.md macOS header-designed backend (~540 LOC)
wiki/getting-started/Game-Modules.md Catalog of all 10 pre-built game modules
(~58K total LOC, was only covered by
the "Creating a Game Module" tutorial)
Rationale — the RHI page already described the abstraction, but only
D3D12 had its own backend page; the other four were referenced in
`RHIFactory::GetRecommendedBackend()` and shipped with full device
implementations yet had nowhere to document format support, capability
detection, validation, or known limitations. The five new pages
complete the RHI backend matrix.
Game-Modules.md fills the most glaring navigation gap: 10 modules
totalling ~58K LOC were discoverable only by reading CMake or browsing
`GameModules/`. Each module now has a catalog entry with LOC, genre,
and the engine subsystems it wires, plus a link to `Creating-a-Game-Module`
for builders who want their own.
Sidebar and docs/README.md updated; wiki-nav check reports 141 pages,
all in sidebar; full-repo link scan reports 37,220 references checked
with 0 broken.
https://claude.ai/code/session_01TuKSsMgreD8WhdcLqhT8E4
Contributor
❌ CI Error ReportFailed jobs: clang-tidy, coverage, linux-asan, linux-clang-Debug, linux-gcc-Debug, linux-msan, linux-tsan, macos-Debug, macos-Release, windows-vs2022-Release Build Errors
Other errors (1)Full error output
|
| Test | Jobs |
|---|---|
| [04:56:35.058] [TID:4316] [WARN ] [Network ] RCON unknown command: nonexistent_cmd (DedicatedServer.cpp:573) | windows-vs2022-Release |
| [04:56:35.074] [TID:4316] [WARN ] [Network ] NetBuffer::ReadUint8 — buffer overrun at pos 1 (size=1) (NetworkBuffer.c... | windows-vs2022-Release |
| [04:56:35.093] [TID:4316] [WARN ] [AI ] BuildNavMeshWithRecast: empty geometry (RecastDetourBackend.cpp:35) | windows-vs2022-Release |
| [04:56:35.094] [TID:4316] [WARN ] [AI ] NavMeshBuilder: Recast build failed, falling back to triangle-soup builder (N... | windows-vs2022-Release |
| [04:56:35.094] [TID:4316] [WARN ] [Audio ] XAudio2 backend requested but no AudioEngine provided, falling back to Nul... | windows-vs2022-Release |
| [ OK ] ProfileProperties_NoResetWhenNotFlagged (0us,[04:56:35.095] [TID:4316] [WARN ] [Graphics ] No graphics backend... | windows-vs2022-Release |
| [04:56:35.095] [TID:4316] [WARN ] [Graphics ] No graphics backend available — falling back to NullRHIDevice (headless... | windows-vs2022-Release |
| [04:56:35.100] [TID:4316] [WARN ] [Editor ] Cannot host: userName is empty. (CollaborativeEditSession.cpp:454) | windows-vs2022-Release |
| [04:56:35.100] [TID:4316] [WARN ] [Editor ] Already connected. (CollaborativeEditSession.cpp:459) | windows-vs2022-Release |
| [04:56:35.103] [TID:4316] [WARN ] [Editor ] BroadcastEdit rejected: nodeId is empty. (CollaborativeEditSession.cpp:1119) | windows-vs2022-Release |
| [04:56:35.103] [TID:4316] [WARN ] [Editor ] BroadcastEdit rejected: sourceEditor is not set. (CollaborativeEditSessio... | windows-vs2022-Release |
| [04:56:35.104] [TID:4316] [WARN ] [Editor ] SetLocalSelection rejected: nodeId exceeds 255 chars (length=300). (Colla... | windows-vs2022-Release |
| [04:56:40.668] [TID:4316] [WARN ] [Network ] Connection rejected for pending client 5: server full (4/4) (NetworkConn... | windows-vs2022-Release |
| [04:56:40.670] [TID:4316] [WARN ] [Network ] Invalid packet magic 0x6A0E5CB3 (expected 0x5350524B) (NetworkManager.cp... | windows-vs2022-Release |
| [04:56:40.670] [TID:4316] [WARN ] [Network ] Invalid packet magic 0xC6BB6E5B (expected 0x5350524B) (NetworkManager.cp... | windows-vs2022-Release |
Compiler Warnings (3)
../SparkEngine/Source/Physics/PhysicsBodyImpl.cpp:270:23: warning: comparing floating point with == or != is unsafe [-Wfloat-equal] [linux-msan]
../SparkEngine/Source/Physics/PhysicsSystem.cpp:401:12: warning: use of old-style cast [-Wold-style-cast] [linux-msan]
../../Tests/TestReliableChannel.cpp:390:9: warning: variable 'retransmitCount' set but not used [-Wunused-but-set-variable] [linux-msan]
Updated: 2026-04-17T04:57:16Z — this comment is updated in-place, not duplicated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.