wesldoc

.

Generate documentation for WESL projects.

Warning: This is a work in progress and not stable in any way yet.

Features

• Generate HTML documentation for WESL projects.
• Search for items or attributes in the documentation.
• Go to source code from the documentation.
• Documentation comments (/// and //!) with Markdown formatting and (currently limited) support for intra-doc links.
• Show translate-time features in the documentation.
• Choose between a dark and a light theme.

For a live example, check out the GitHub Pages site of this repository.

How to use

Use the CLI

First install the wesldoc CLI:

cargo install wesldoc --locked --path ./crates/wesldoc

Then use it like this:

wesldoc ./path/to/my_wesl_project

Check wesldoc --help for more options.

Note: Dependencies are resolved using the wesl.toml file in the root of the project. Currently the dependencies are not built recursively, this will be addressed in the future.

Note: Currently only cargo is supported as package manager. Support for other package managers may be added in the future.

Use as a library

The wesldoc CLI is just a wrapper around the wesldoc_compiler and wesldoc_generator crates. You can use them directly in your own projects. Look at the wesldoc crate for an example on how to use them.

How it works

• wesldoc_ast: This crate provides the AST for the WESL documentation. It is fully standalone and does not depend on wesl-rs.
• wesldoc_generator: This crate takes a WeslDocs from wesldoc_ast and generates the documentation in HTML format.
• wesldoc_compiler: This crate takes the compile results from wesl-rs and compiles them into a WeslDocs object. It is agnostic to how the packages where resolved and compiled, but requires the availability of source maps to work properly.
• wesldoc: This crate is a wrapper around wesldoc_compiler and wesldoc_generator. It provides a CLI to generate the documentation from WESL packages. It uses wesl-rs to resolve and compile the packages, and then generates the documentation using wesldoc_compiler and wesldoc_generator.

Note: Certain features of wesldoc may be migrated to wesldoc_compiler in the future once a standardized method for packaging WESL projects is established.

Development

To build the example packages, run:

cargo run --example build_examples

License

Licensed under either of

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.