bevy_docs_extension_demo

A crate for testing rustdoc extensions and configurations for the Bevy game engine.

Building Locally

To apply documentation extensions to local builds, you must provide cargo doc with the relevant arguments for RUSTDOCFLAGS to configure the output of rustdoc. See the rustdoc documentation for a list of available arguments.

For example, building the docs with the trait-tags extension and --no-deps can be done with the following command:

RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html" cargo doc --no-deps

Note that if documentation is also built for other dependencies, you must provide absolute paths instead of relative paths for files:

RUSTDOCFLAGS="--html-after-content path/to/docs-rs/trait-tags.html" cargo doc

Building on Docs.rs

Extensions can be applied to docs.rs builds by providing the relevant arguments for rustdoc-args in your Cargo.toml. See the rustdoc documentation for a list of available arguments.

For example, building the docs with the trait-tags extension can be done with the following configuration:

[package.metadata.docs.rs]
rustdoc-args = ["--html-after-content", "docs-rs/trait-tags.html"]

See Cargo.toml for the configuration passed to docs.rs for building this crate.

Trait Tags

This extension adds tags on types to indicate usage based on Bevy traits such as Component, Event, etc.

For trait tags to show in listings, metadata needs to be embedded within the source files. You likely do not want to commit this to version control on a branch that receives new manual changes. Run the embed-trait-info tool by pointing it at your project workspace (using --root-dir if it doesn't match the working directors) and give it the names of the packages to modify, e.g.

cargo run -p embed-trait-info bevy_docs_extension_demo

before building the documentation as above.

License

All code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.