chore(docs): Update documentation structure (#174)

vmarcella · web-flow · commit b96df38f82f7 · 2026-02-06T17:07:03.000-08:00
## Summary

Organize `lambda-rs` specifications and tutorials into feature-based
subdirectories (rendering/audio/runtime).

## Related Issues

## Changes

- Move specs into feature subdirectories:
  - Rendering: `docs/specs/rendering/`
  - Audio: `docs/specs/audio/`
  - Runtime/events: `docs/specs/runtime/`
- Move tutorials into feature subdirectories:
  - `docs/tutorials/rendering/basics/`
  - `docs/tutorials/rendering/resources/`
  - `docs/tutorials/rendering/techniques/`
- Update indexes:
- `docs/specs/README.md` now groups specs by feature area and links to
the new paths.
- `docs/tutorials/README.md` now groups tutorials by feature area/level
and links to the new paths.
- Update references to moved docs:
  - `README.md` tutorial links updated.
  - `CONTRIBUTING.md` updated with new specs organization guidance.
- `docs/specs/_spec-template.md` updated to instruct placing specs under
area folders and adding them to the specs index.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] Feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation (updates to docs, specs, tutorials, or comments)
- [ ] Refactor (code change that neither fixes a bug nor adds a feature)
- [ ] Performance (change that improves performance)
- [ ] Test (adding or updating tests)
- [ ] Build/CI (changes to build process or CI configuration)

## Affected Crates

- [x] `lambda-rs`
- [ ] `lambda-rs-platform`
- [ ] `lambda-rs-args`
- [ ] `lambda-rs-logging`
- [ ] Other:

## Checklist

- [ ] Code follows the repository style guidelines (`cargo +nightly fmt
--all`)
- [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D
warnings`)
- [ ] Tests pass (`cargo test --workspace`)
- [x] New code includes appropriate documentation
- [ ] Public API changes are documented
- [ ] Breaking changes are noted in this PR description

## Testing

N/A

## Screenshots/Recordings

N/A (documentation move/link updates only).

## Platform Testing

- [ ] macOS
- [ ] Windows
- [ ] Linux

## Additional Notes

- This PR changes doc file paths; any external deep links to the old
locations will break and should be updated.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -72,6 +72,8 @@ When adding or modifying features:
 - Update rustdoc comments for public APIs.
 - Add or update examples in `crates/lambda-rs/examples/`.
 - Create or update specifications in `docs/specs/` for significant changes.
+  - Add new specs to `docs/specs/README.md` and group them by feature area.
+  - Place new specs under a matching subdirectory (for example, `docs/specs/rendering/`).
 - Follow the documentation tone and style guidelines in `AGENTS.md`.
 
 ## Questions and Discussions
diff --git a/README.md b/README.md
@@ -130,7 +130,7 @@ Coming soon.
 Start with the tutorials to build features step by step:
 
 * Tutorials index: [docs/tutorials/](./docs/tutorials/)
-* Uniform Buffers: Build a Spinning Triangle: [docs/tutorials/uniform-buffers.md](./docs/tutorials/uniform-buffers.md)
+* Uniform Buffers: Build a Spinning Triangle: [docs/tutorials/rendering/resources/uniform-buffers.md](./docs/tutorials/rendering/resources/uniform-buffers.md)
 
 ## Examples <a name="examples"></a>
 
diff --git a/docs/specs/README.md b/docs/specs/README.md
@@ -0,0 +1,33 @@
+---
+title: "Specifications Index"
+document_id: "specs-index-2026-02-07"
+status: "living"
+created: "2026-02-07T00:00:00Z"
+last_updated: "2026-02-07T00:00:00Z"
+version: "0.1.0"
+owners: ["lambda-sh"]
+reviewers: ["engine"]
+tags: ["index", "specs", "docs"]
+---
+
+## Rendering
+
+- Uniform Buffers and Bind Groups — [rendering/uniform-buffers-and-bind-groups.md](rendering/uniform-buffers-and-bind-groups.md)
+- Textures and Samplers — [rendering/textures-and-samplers.md](rendering/textures-and-samplers.md)
+- Instanced Rendering — [rendering/instanced-rendering.md](rendering/instanced-rendering.md)
+- Indexed Draws and Multiple Vertex Buffers — [rendering/indexed-draws-and-multiple-vertex-buffers.md](rendering/indexed-draws-and-multiple-vertex-buffers.md)
+- Depth, Stencil, and MSAA — [rendering/depth-stencil-msaa.md](rendering/depth-stencil-msaa.md)
+- Offscreen Render Targets and Multipass — [rendering/offscreen-render-targets-and-multipass.md](rendering/offscreen-render-targets-and-multipass.md)
+
+## Audio
+
+- Audio Devices — [audio/audio-devices.md](audio/audio-devices.md)
+- Audio File Loading — [audio/audio-file-loading.md](audio/audio-file-loading.md)
+
+## Runtime / Events
+
+- Component Event Handling — [runtime/component-event-handling.md](runtime/component-event-handling.md)
+
+## Templates
+
+- Specification template — [_spec-template.md](_spec-template.md)
diff --git a/docs/specs/_spec-template.md b/docs/specs/_spec-template.md
@@ -17,6 +17,9 @@ tags: ["spec", "<area>"]
 
 # <Specification Title>
 
+Note: Place specifications under the appropriate area folder (for example,
+`docs/specs/rendering/`) and add them to `docs/specs/README.md`.
+
 Summary
 - State the problem and the desired outcome in one paragraph.
 - Include a concise rationale for introducing or changing behavior.
diff --git a/docs/specs/audio/audio-devices.md b/docs/specs/audio/audio-devices.md
@@ -3,7 +3,7 @@ title: "Audio Device Abstraction"
 document_id: "audio-device-abstraction-2026-01-28"
 status: "draft"
 created: "2026-01-28T22:59:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.18"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/audio/audio-file-loading.md b/docs/specs/audio/audio-file-loading.md
@@ -3,7 +3,7 @@ title: "Audio File Loading (SoundBuffer)"
 document_id: "audio-file-loading-2026-01-31"
 status: "draft"
 created: "2026-01-31T22:07:49Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.3"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/depth-stencil-msaa.md b/docs/specs/rendering/depth-stencil-msaa.md
@@ -3,7 +3,7 @@ title: "Depth/Stencil and Multi-Sample Rendering"
 document_id: "depth-stencil-msaa-2025-11-11"
 status: "draft"
 created: "2025-11-11T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/indexed-draws-and-multiple-vertex-buffers.md b/docs/specs/rendering/indexed-draws-and-multiple-vertex-buffers.md
@@ -3,7 +3,7 @@ title: "Indexed Draws and Multiple Vertex Buffers"
 document_id: "indexed-draws-multiple-vertex-buffers-2025-11-22"
 status: "draft"
 created: "2025-11-22T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/instanced-rendering.md b/docs/specs/rendering/instanced-rendering.md
@@ -3,7 +3,7 @@ title: "Instanced Rendering"
 document_id: "instanced-rendering-2025-11-23"
 status: "draft"
 created: "2025-11-23T00:00:00Z"
-last_updated: "2025-11-25T02:20:00Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.5"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/offscreen-render-targets-and-multipass.md b/docs/specs/rendering/offscreen-render-targets-and-multipass.md
@@ -3,7 +3,7 @@ title: "Offscreen Render Targets and Multipass Rendering"
 document_id: "offscreen-render-targets-2025-11-25"
 status: "draft"
 created: "2025-11-25T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.6"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/textures-and-samplers.md b/docs/specs/rendering/textures-and-samplers.md
@@ -3,7 +3,7 @@ title: "Textures and Samplers"
 document_id: "texture-sampler-spec-2025-10-30"
 status: "draft"
 created: "2025-10-30T00:00:00Z"
-last_updated: "2025-12-15T00:00:00Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.0"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/specs/rendering/uniform-buffers-and-bind-groups.md b/docs/specs/rendering/uniform-buffers-and-bind-groups.md
@@ -3,7 +3,7 @@ title: "Uniform Buffers and Bind Groups"
 document_id: "ubo-spec-2025-10-11"
 status: "living"
 created: "2025-10-11T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
@@ -275,7 +275,7 @@ RC::SetBindGroup { set: 0, group: dyn_group_id, dynamic_offsets: offsets };
   - [x] Dynamic offset alignment/count checks — crates/lambda-rs/src/render/validation.rs
 - Performance
   - [x] Recommendations documented (this section)
-  - [x] Dynamic offsets example provided — docs/specs/uniform-buffers-and-bind-groups.md
+  - [x] Dynamic offsets example provided — docs/specs/rendering/uniform-buffers-and-bind-groups.md
 - Documentation and Examples
   - [x] Spec updated (this document)
   - [x] Example added — demos/render/src/bin/uniform_buffer_triangle.rs
diff --git a/docs/specs/runtime/component-event-handling.md b/docs/specs/runtime/component-event-handling.md
@@ -3,7 +3,7 @@ title: "Component Event Handling"
 document_id: "component-event-handling-2026-01-10"
 status: "draft"
 created: "2026-01-10T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.1.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
@@ -214,10 +214,10 @@ winit event loop
   - [x] `Component` trait documentation updated (Ref:
     `docs/rendering.md`)
   - [x] Backwards compatibility assessed and migration documented (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
 - Validation and Errors
   - [x] Error behavior specified for handler failures (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
   - [x] Runtime publishes `RuntimeEvent::ComponentPanic` on handler errors
     (Ref: `crates/lambda-rs/src/runtimes/application.rs`)
 - Performance
@@ -231,7 +231,7 @@ winit event loop
   - [x] `docs/features.md` checked for relevance (no new features expected)
     (Ref: `docs/features.md`)
   - [x] Migration notes added to component documentation (Ref:
-    `docs/specs/component-event-handling.md`)
+    `docs/specs/runtime/component-event-handling.md`)
 
 For each checked item, include a reference to a commit, pull request, or file
 path that demonstrates the implementation.
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
@@ -3,8 +3,8 @@ title: "Tutorials Index"
 document_id: "tutorials-index-2025-10-17"
 status: "living"
 created: "2025-10-17T00:20:00Z"
-last_updated: "2026-01-05T00:00:00Z"
-version: "0.7.0"
+last_updated: "2026-02-07T00:00:00Z"
+version: "0.7.1"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
 shader_backend_default: "naga"
@@ -17,19 +17,31 @@ tags: ["index", "tutorials", "docs"]
 
 This index lists tutorials that teach specific `lambda-rs` tasks through complete, incremental builds.
 
-- Basic Triangle: Vertex‑Only Draw — [basic-triangle.md](basic-triangle.md)
-- Immediates: Draw Multiple 2D Triangles — [immediates-multiple-triangles.md](immediates-multiple-triangles.md)
-- Uniform Buffers: Build a Spinning Triangle — [uniform-buffers.md](uniform-buffers.md)
-- Textured Quad: Sample a 2D Texture — [textured-quad.md](textured-quad.md)
-- Textured Cube: 3D Immediates + 2D Sampling — [textured-cube.md](textured-cube.md)
-- Offscreen Post: Render to a Texture and Sample to the Surface — [offscreen-post.md](offscreen-post.md)
-- Reflective Room: Stencil Masked Reflections with MSAA — [reflective-room.md](reflective-room.md)
-- Instanced Rendering: Grid of Colored Quads — [instanced-quads.md](instanced-quads.md)
+## Rendering
 
-Browse all tutorials in this directory.
+### Basics
+
+- Basic Triangle: Vertex‑Only Draw — [rendering/basics/basic-triangle.md](rendering/basics/basic-triangle.md)
+- Immediates: Draw Multiple 2D Triangles — [rendering/basics/immediates-multiple-triangles.md](rendering/basics/immediates-multiple-triangles.md)
+
+### GPU Resources
+
+- Uniform Buffers: Build a Spinning Triangle — [rendering/resources/uniform-buffers.md](rendering/resources/uniform-buffers.md)
+- Textured Quad: Sample a 2D Texture — [rendering/resources/textured-quad.md](rendering/resources/textured-quad.md)
+- Textured Cube: 3D Immediates + 2D Sampling — [rendering/resources/textured-cube.md](rendering/resources/textured-cube.md)
+
+### Techniques
+
+- Indexed Draws and Multiple Vertex Buffers — [rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md](rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md)
+- Instanced Rendering: Grid of Colored Quads — [rendering/techniques/instanced-quads.md](rendering/techniques/instanced-quads.md)
+- Offscreen Post: Render to a Texture and Sample to the Surface — [rendering/techniques/offscreen-post.md](rendering/techniques/offscreen-post.md)
+- Reflective Room: Stencil Masked Reflections with MSAA — [rendering/techniques/reflective-room.md](rendering/techniques/reflective-room.md)
+
+Browse all tutorials under `rendering/`.
 
 Changelog
 
+- 0.7.1 (2026-02-07): Group tutorials by feature area in the index.
 - 0.7.0 (2026-01-05): Rename push constants tutorial to immediates for wgpu v28; update metadata.
 - 0.6.0 (2025-12-29): Add offscreen post tutorial; update metadata and commit.
 - 0.5.0 (2025-12-16): Add basic triangle and multi-triangle push constants tutorials; update metadata and commit.
diff --git a/docs/tutorials/rendering/basics/basic-triangle.md b/docs/tutorials/rendering/basics/basic-triangle.md
@@ -3,7 +3,7 @@ title: "Basic Triangle: Vertex‑Only Draw"
 document_id: "basic-triangle-tutorial-2025-12-16"
 status: "draft"
 created: "2025-12-16T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
diff --git a/docs/tutorials/rendering/basics/immediates-multiple-triangles.md b/docs/tutorials/rendering/basics/immediates-multiple-triangles.md
@@ -3,7 +3,7 @@ title: "Immediates: Draw Multiple 2D Triangles"
 document_id: "immediates-multiple-triangles-tutorial-2025-12-16"
 status: "draft"
 created: "2025-12-16T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
diff --git a/docs/tutorials/rendering/resources/textured-cube.md b/docs/tutorials/rendering/resources/textured-cube.md
@@ -3,7 +3,7 @@ title: "Textured Cube: 3D Immediates + 2D Sampling"
 document_id: "textured-cube-tutorial-2025-11-10"
 status: "draft"
 created: "2025-11-10T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.3.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
diff --git a/docs/tutorials/rendering/resources/textured-quad.md b/docs/tutorials/rendering/resources/textured-quad.md
@@ -3,7 +3,7 @@ title: "Textured Quad: Sample a 2D Texture"
 document_id: "textured-quad-tutorial-2025-11-01"
 status: "draft"
 created: "2025-11-01T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/tutorials/rendering/resources/uniform-buffers.md b/docs/tutorials/rendering/resources/uniform-buffers.md
@@ -3,7 +3,7 @@ title: "Uniform Buffers: Build a Spinning Triangle"
 document_id: "uniform-buffers-tutorial-2025-10-17"
 status: "draft"
 created: "2025-10-17T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.5.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/tutorials/rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md b/docs/tutorials/rendering/techniques/indexed-draws-and-multiple-vertex-buffers.md
@@ -3,7 +3,7 @@ title: "Indexed Draws and Multiple Vertex Buffers"
 document_id: "indexed-draws-multiple-vertex-buffers-tutorial-2025-11-22"
 status: "draft"
 created: "2025-11-22T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.3.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/tutorials/rendering/techniques/instanced-quads.md b/docs/tutorials/rendering/techniques/instanced-quads.md
@@ -3,7 +3,7 @@ title: "Instanced Rendering: Grid of Colored Quads"
 document_id: "instanced-quads-tutorial-2025-11-25"
 status: "draft"
 created: "2025-11-25T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.4"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/tutorials/rendering/techniques/offscreen-post.md b/docs/tutorials/rendering/techniques/offscreen-post.md
@@ -3,7 +3,7 @@ title: "Offscreen Post: Render to a Texture and Sample to the Surface"
 document_id: "offscreen-post-tutorial-2025-12-29"
 status: "draft"
 created: "2025-12-29T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.2.2"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
diff --git a/docs/tutorials/rendering/techniques/reflective-room.md b/docs/tutorials/rendering/techniques/reflective-room.md
@@ -3,7 +3,7 @@ title: "Reflective Floor: Stencil‑Masked Planar Reflections"
 document_id: "reflective-room-tutorial-2025-11-17"
 status: "draft"
 created: "2025-11-17T00:00:00Z"
-last_updated: "2026-02-05T23:05:40Z"
+last_updated: "2026-02-07T00:00:00Z"
 version: "0.4.5"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "28.0.0"
