Docs - Auto generate examples docs

[VaclavElias]

Can we auto generate docs for easier maintance?

See the header here https://www.raylib.com/examples/core/loader.html?name=core_input_keys

Similar could be generated for the examples docs.

Structure

• Category: Keep a single primary Category for navigation. Use Tags for cross-cutting facets. If you ever need multiple, add a separate optional Categories: [] later, but don’t rely on it now.
• Complexity: Yes, include Complexity: 1–5. It’s useful for sorting and filtering.
• Loading meta: Don’t parse source at runtime in production. Generate a manifest (JSON) at build time and load that in the launcher. Optionally allow runtime scanning only in dev-mode as a fallback.

Recommended schema strategy

• Required fields: Id, Title, Category, Level, Complexity, Order
• Optional: Description, Concepts[], Related[], Tags[]
• Level values (controlled): GettingStarted, Basic, Intermediate, Advanced
• Category values (controlled, single): Core, Shapes, Materials, Textures, Cameras, Lighting, Physics, UI, Input, Audio, Rendering, Shaders, Models, Particles, Networking, Tools
• Tags: free-form, but normalize to kebab-case for filters (e.g., capsule, primitive, scene-setup, transform, skybox)

Tags for this example

• capsule, primitive, shapes, transform, position, skybox, scene-setup, getting-started

Loader/Docs flow

• Build-time extraction (recommended):
  • A small extractor scans examples for EXAMPLE_META, validates the schema, and emits examples-manifest.json.
  • For Blazor WASM launcher: place the JSON in wwwroot and fetch it.
  • For Blazor Server or desktop launcher: load from content file or embedded resource.
• Runtime extraction (dev-only fallback):
  • If manifest missing, scan Program.cs files at startup, extract EXAMPLE_META, and cache the result. This won’t work for WASM and is slower, so keep it for development only.

Operational notes

• Use Id derived from the example folder name to keep links stable.
• Sorting: Level > Category > Order > Title.
• Validation: add a CI step to ensure every example contains valid metadata and uses allowed Level/Category values.
• Forward compatibility: you can later add Categories: [] without breaking existing consumers; prefer Category for primary grouping.

Example

/*
EXAMPLE_META_START
Title: Basic3D Scene (Capsule)
Category: Shapes
Level: Getting Started
Complexity:1
Order:1
Description: |
 Create a minimal 3D scene using toolkit helpers and place a single capsule primitive.
 Demonstrates entity creation, basic positioning, and attaching the entity to the scene.
Concepts:
 - Creating a 3D primitive (Capsule)
 - Positioning an entity with Transform.Position
 - Adding entities to a Scene (rootScene)
 - Using helpers: SetupBase3DScene and AddSkybox
Related:
 - Example02_GiveMeACube
 - Example01_Basic3DScene_Primitives
 - Example01_Material
Tags:
 -3D
 - Shapes
 - Primitive
 - Capsule
 - Scene Setup
 - Skybox
 - Transform
 - Position
 - Getting Started
EXAMPLE_META_END
*/

[VaclavElias]

Let's brainstorm approaches for embedding example metadata directly in Program.cs to reduce maintenance overhead. Here are several strategies:

Option 1: XML Documentation Comments (Top of File)

Use standard C# XML doc comments with custom tags at the top of Program.cs:

Pros:
• Single source of truth in Program.cs
• Standard C# comment format (parseable with Roslyn)
• Visible when reading the code
Cons:
• Non-standard XML tags (won't be recognized by IDE tooling)
• Parsing requires custom tooling

/// <example-metadata>
/// <title>Capsule with rigid body</title>
/// <category>Basic Example</category>
/// <order>100</order>
/// <description>
/// Demonstrates creating a 3D capsule with a rigid body component in a basic scene.
/// Shows how to position entities and add physics.
/// </description>
/// <concepts>
/// - 3D primitive creation
/// - Rigid body physics
/// - Entity positioning
/// </concepts>
/// <relatedExamples>
/// - Example07_GiveMeCube
/// - Example02_CapsuleWithRigidBodyBullet
/// </relatedExamples>
/// </example-metadata>

Option 2: Structured Comments (Bottom of File)

Pros:
• Clear separation from code
• Easy to parse (YAML-like or custom format)
• Doesn't clutter top of file
Cons:
• Less discoverable (at bottom)
• Still requires custom parsing

2. Create a doc generation tool (e.g., in docs/ folder):
   • Scan all examples/code-only/*/Program.cs files
   • Extract metadata between ---EXAMPLE-META--- and ---END-META---
   • Generate markdown files or update existing doc pages

/*
EXAMPLE_META_START
Title: Capsule with rigid body
Category: Basic Example
Order: 100
Description: |
  Demonstrates creating a 3D capsule with a rigid body component in a basic scene.
  Shows how to position entities and add physics using Bepu.
Concepts:
  - 3D primitive creation
  - Rigid body physics (Bepu)
  - Entity positioning
Related:
  - Example07_GiveMeCube
  - Example02_CapsuleWithRigidBodyBullet
EXAMPLE_META_END
*/

or

/*
## Example Documentation
### Description
Demonstrates creating a 3D capsule with a rigid body component in a basic scene.

### Key Concepts
- Using `Create3DPrimitive` to generate geometry
- Positioning entities with `Transform.Position`
- Bepu physics integration

### Related Examples
- [Give me a cube](../Example07_GiveMeCube)
- [Capsule with Bullet physics](../Example02_CapsuleWithRigidBodyBullet)
*/

Option 3: Assembly-Level Attributes

Use C# attributes (though typically these are for assemblies, you could extend this pattern):

Pros:
• Strongly typed
• Compile-time validation
Cons:
• Requires defining custom attribute classes
• More verbose
• Reflection or source generation needed for extraction

[assembly: ExampleMetadata(
Title = "Capsule with rigid body",
Category = "Basic Example",
Order = 100,
Description = "Demonstrates creating a 3D capsule with a rigid body component.")]

[VaclavElias]

Recommendations
• Tags: Use concise tokens that map to filters. Keep singular nouns. Good for launcher filtering.
• Complexity: Yes, add it. Scale 1-5 is fine. Use:
• 1: trivial, one concept
• 2: basic, 2-3 concepts
• 3: intermediate, multiple systems combined
• 4: advanced, custom shaders/physics pipelines/async systems
• 5: expert, engine-level features or performance tuning
• Level vs Category:
• Level: Getting Started | Basic | Intermediate | Advanced
• Category: domain/topic area such as:
• Core, Shapes, Materials, Textures, Cameras, Lighting, Physics, UI, Input, Audio, Rendering, Shaders, Models, Particles, Networking, Tools
• Order: Keep unique within Category + Level if you want consistent sort.