wgsldoc 📃🧑‍💻

wgsldoc is a documentation generator for WGSL (WebGPU Shading Language) shader modules. It parses .wgsl files, extracts documentation comments, and generates a structured, searchable HTML site for easy browsing and reference.

Installation

To install wgsldoc, you can use Cargo, the Rust package manager. Run the following command:

cargo install wgsldoc

Usage

After installation, you can run wgsldoc from the command line. The following command will generate documentation for all WGSL files (including README.md and favicon.png files) in the current directory, outputting the result to the docs directory:

wgsldoc

If you want to host your docs as a website, you should specify a base URL with the -U option:

wgsldoc -U https://example.com/docs

If you want to only generate the AST (Abstract Syntax Tree) and print it to stdout (or another stream) instead of generating full documentation, you can use the -A option:

wgsldoc -A > ast_output.txt

or for stdout

wgsldoc -A

AST example:

Simple shader:

@group(0) @binding(0) var<uniform> color: vec4<f32>;

@fragment
fn main() -> @location(0) vec4<f32> {
    return color;
}

simple => Wgsl {
    module_name: "simple",
    source_code: "...",
    global_docs: None,
    imports: [],
    functions: [
        Function {
            docs: None,
            name: "main",
            args: [],
            return_ty: Some(
                Vector(
                    Vector {
                        dimension: D4,
                        ty: Float32,
                    },
                ),
            ),
        },
    ],
    structures: [],
    constants: [],
    bindings: [
        Binding {
            docs: None,
            attr_group: 0,
            attr_binding: 0,
            name: "color",
            ty: Vector(
                Vector {
                    dimension: D4,
                    ty: Float32,
                },
            ),
        },
    ],
}

More advanced usage:

Usage: wgsldoc [OPTIONS]

Options:
  -N, --name <NAME>              Name of the package to generate documentation for
  -D, --target-dir <TARGET_DIR>  Target directory for the generated documentation 
  -U, --base-url <BASE_URL>      Base URL for future website. If specified, it will be used to generate links in the documentation. Otherwise, the links will use `target_dir` as the base URL
  -A, --ast-only                 Generate AST and print it to stdout instead of generating full documentation
  -I, --input <FILES>            Input files to process. If not specified, the program will look for .wgsl files in the current directory
  -W, --show-undocumented        Show undocumented items in the documentation
  -C, --credits                  Show credits
  -h, --help                     Print help (see more with '--help')
  -V, --version                  Print version

Features

• CLI
  • AST-only mode
  • Documentation generation
  • Show undocumented items
• Parsing
  • Modules
  • Imports
  • Functions
  • Structures
  • Constants
  • Bindings
• HTML Generation
  • Main page
  • Modules
    • Index page
    • Module page
    • Import page
    • Function page
    • Structure page
    • Constants page
    • Bindings page
  • Source code
• Documentation