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