Feat: Implement Automated MDX Documentation Generator

[MichaelFisher1997]

Summary

Implement a Zig-based documentation generator (tools/docgen.zig) that uses std.zig.Ast to extract documentation from source files and output MDX files compatible with Docusaurus.

Requirements (Zig Side)

• Static Analysis: Must use std.zig.Ast to parse Zig source without compilation.
• Extraction:
  • Module-level documentation (//!).
  • Doc comments (///) for all pub declarations (structs, enums, functions, constants).
  • Reconstruction of function signatures and type definitions.
• Structure: Output MDX files should mirror the src/ directory structure in a target directory (e.g., docs/generated/).
• Build System: Integrate as a build step (zig build docs).

Requirements (CI/Pipeline)

• GitHub Action: Automate the generation on push to main.
• Artifacts: Upload the generated MDX files as a build artifact for consumption by the Docusaurus site repo.

Information for Doc Site Builders

• Output Format: Standard MDX files with YAML frontmatter.
• Asset Handling: Any images or diagrams in doc comments should refer to absolute paths in the engine repo or a shared CDN.
• Sidebar Integration: The generated directory structure is intended to be used with Docusaurus's autogenerated sidebars.
• Custom Components: The MDX will use standard Markdown blocks for code ( zig), so ensure a Zig syntax highlighter is configured in Docusaurus.

[opencode-agent]

Created PR #208

opencode session  |  github run

[MichaelFisher1997]

/oc
Analyze this issue. You have access to the codebase context.
CRITICAL: Your only allowed action is to post a COMMENT on the issue. DO NOT create branches, pull requests, or attempt to modify the codebase.

        1. **Classify**: Determine if this is a Bug, Feature Request, or Question.
        2. **Validate & Request Info**:
           - **Missing Data**: If critical information is needed to understand or reproduce the issue (e.g., reproduction steps, crash logs, version numbers, screenshots), explicitly ask the user to provide it.
        3. **Analyze**:
           - If a stack trace or error is provided, analyze the codebase to find the root cause and provide code pointers.
           - If it's a feature request, briefly summarize the architectural impact.
        4. **Action**:
           - Your response MUST be a comment on the issue.
           - If you can provide a potential fix or documentation link, describe it in the comment but do NOT implement it.
           - If you need more info, specify exactly what is missing.
           - If the issue is vague, spam, or you have nothing valuable to add: **DO NOT COMMENT**.

[opencode-agent]

This is a well-structured Feature Request for a Zig documentation generator. Let me analyze the feasibility and provide guidance:

Analysis

Implementation Feasibility: High. Zig's standard library provides excellent AST parsing via std.zig.Ast, making this achievable without external dependencies.

Architectural Considerations:

1. AST Parsing Strategy (src/world/block.zig:1-50 as reference):

   • Use std.zig.Ast.parse() to iterate through top-level declarations
   • Distinguish between functions, structs, enums, constants via node_tags
   • Extract doc comments by checking nodes preceding declarations

2. Output Structure:

   • Mirror src/ layout: src/engine/core/ → docs/generated/engine/core.mdx
   • YAML frontmatter with title, sidebar_position, tags

3. Build Integration (build.zig reference needed):

   • Add DocsStep type similar to existing build steps
   • Register under zig build --help options

4. MDX Requirements:

   • Code blocks: ````markdown

• Function signatures need careful reconstruction from AST nodes
• Type definitions may need multi-line formatting

Potential Challenges:

• Preserving import statements for type resolution
• Handling generic functions/types (e.g., Vec3(u32))
• Cross-references between modules

Recommended Next Steps:

1. Create tools/docgen.zig with a minimal prototype parsing one file
2. Test extraction on a complex file like src/world/chunk.zig
3. Define the MDX frontmatter schema before scaling

The existing code organization (src/engine/, src/world/) aligns well with Docusaurus sidebar conventions. Would you like me to provide more specific guidance on any aspect?

opencode session  |  github run

[MichaelFisher1997]

Closing this as superseded by the refreshed phased docs pipeline in #609. The original request is still valuable, but it targeted the older repo layout and bundled strategy, extraction, MDX output, CI, and Docusaurus integration into one issue. The replacement plan splits that work into focused follow-ups: #610, #611, #612, #613, #614, and #615.