tracking issue: examples

[mockersf]

#225 introduced a new page for wasm examples at https://bevyengine.org/examples/

This page is currently lacking in style and not linked from the website. I think it should be the main page for example discovery instead of the git repo:

• it is easier to ensure that the examples are at the latest tag instead of main as the website is only about latest
• it is easier to evolve organisation with tags and categories instead of just a list of folders
• it is easier to control presentation as GitHub will always show files first, then the optional readme.md
• it is easier to have a nice presentation instead of just one large and basic readme.md

So... in case it's not clear, I think it would be easier.

What would be needed to get it in top shape:

• add medatada to Cargo.toml about each example [Merged by Bors] - Examples metadata in Cargo.toml bevy#4741
  • display name
  • description
  • wasm enabled
• add an example page built with the dev docs
• update the website to display all examples with their metadata, but only build wasm version for the one where it is enabled
  • WebGPU: Webgpu example pages #630
  • WebGL2: Examples update #720
  • non Wasm compatible: Show WASM-incompatible examples #1024
• remove/simplify the readme.md in bevy repo example folder. This file can't scale
• link more prominently to the website for examples [Merged by Bors] - Make web examples more visible #335
• (optional) add screenshot of the examples as part of the metadata Webgpu example pages #630
• (optional) add tags to the metadata to help with discovery Add Search on Examples page #742

This should be tied with #159 (bevy assets page) to evolve a consistent style.

The first two points need to be done before a release, the two next with that release

[cart]

I love these ideas. Is there a good way to specify custom per-example metadata in Cargo.toml? I think id prefer that if its possible. If not, a single centralized file for this config has my preference. I dont want to throw a bunch of metadata in custom per file header format, or have a bunch of per-example config files. That could be weird/confusing for users.

[mockersf]

Is there a good way to specify custom per-example metadata in Cargo.toml?

It's possible to add any field we want in the Cargo.toml file:

[[example]]
name = "3d_scene"
path = "examples/3d/3d_scene.rs"
display_name = "3D Scene"
description = "Simple 3D scene with basic shapes and lighting"

but this issues warnings:

warning: /bevy/Cargo.toml: unused manifest key: example.13.description
warning: /bevy/Cargo.toml: unused manifest key: example.13.display_name

[mockersf]

I posted https://internals.rust-lang.org/t/cargo-manifest-and-unused-manifest-key-allow-other-tools-to-extend-the-manifest/16333 as that would be the best solution if only there was a way to remove that warning

[cart]

Maybe we could use this: https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table?

[[example]]
name = "3d_scene"
path = "examples/3d/3d_scene.rs"

[package.metadata.example.3d_scene]
display_name = "3D Scene"
description = "Simple 3D scene with basic shapes and lighting"

[cart]

Sadly a bit verbose + redundant (example.3d_scene would need to match name = "3d_scene"), but it might work :)

[mockersf]

I would love for this to work:

[[example]]
name = "3d_scene"
path = "examples/3d/3d_scene.rs"

[example.metadata]
display_name = "3D Scene"
description = "Simple 3D scene with basic shapes and lighting"

Array of Tables: Any reference to an array of tables points to the most recently defined table element of the array. This allows you to define sub-tables, and even sub-arrays of tables, inside the most recent table. That means the metadata field would refer to the example defined just above

I looked a little into cargo code, it wouldn't be hard to add, I'll check if they would accept a PR for that

[BD103]

Here is an updated checklist:

• add metadata to Cargo.toml about each example [Merged by Bors] - Examples metadata in Cargo.toml bevy#4741
• add an example page built with the dev docs
  • Given how building all of the WASM examples takes roughly 2.5 hours, I don't think this is viable
• update the website to display all examples with their metadata, but only build wasm version for the one where it is enabled
  • Related: Show WASM-incompatible examples #1024
• remove/simplify the readme.md in bevy repo example folder. This file can't scale
  • Perhaps an individual README.md can be created per subdirectory: one for 2d, one for ecs, etc.
• link more prominently to the website for examples [Merged by Bors] - Make web examples more visible #335
• (optional) add screenshot of the examples as part of the metadata
• (optional) add tags to the metadata to help with discovery