Reorganize existing examples into "api"/"usage"/"games"

[inodentry]

This PR reorganizes Bevy's examples for easier navigation and maintenance. It follows the new "API/Usage" categorization as described here.

Scope

The scope of this PR is:

• Rename/move all existing examples to follow our new conventions.
• Split up the README.md file accordingly.
• Improve the readability and organization of the examples READMEs.

TODO

• Decide which of our existing examples are more applicable for the new "Usage" example kind, rather than "API" or "Games".
• Move those examples to examples/usage/ and categorize them in a way that makes sense. These are new categories, different from the ones for API examples.
• Move examples/stress_tests/ to top-level stress-tests/.
• Move examples/testbed/* to tests/.
• Leave examples/tools/ as is.
• Leave examples/wasm/ and examples/mobile/ as is.
• Move the remaining example categories to examples/api/.
• Update Cargo.toml accordingly.
  • Add new kind field to [package.metadata.example.*] sections.
• Create separate README.md files for each example kind with their own tables of contents and example listings.
• Replace the ToC and example listings in examples/README.md with brief descriptions of our example kinds and links to their READMEs.
• Create separate examples/mobile/README.md and examples/wasm/README.md files and move the platform-specific info from examples/README.md there.
• Create follow-up PR to bevy-website to ensure the Contributing Book page is consistent with whatever we ultimately do here.
• Update all tooling that relies on examples metadata and organization (@mockersf please help!)
  • Bevy Website and the tools to generate the example pages
    • Examples now need to be organized by kind and category.
  • The tools to assist contributors
    • The script for automatically editing the README needs to use the correct README.
  • CI?
  • Others?

@alice-i-cecile and I made many of these decisions together at the RustWeek Bevy Unconf and I have now done the relevant work.

That said, until this PR is merged, all of this is still open to community feedback. As this is a "bikesheddy" question, please try to provide substantial arguments if you suggest changes.

Remaining Questions

• I don't quite understand what is the difference between examples/testbed/ and tests/ currently and I don't know if it can simply be moved there or if anything needs to be changed.
• Do we want to use [[bin]] targets or separate workspace packages, instead of [[example]] in Cargo.toml for stress tests? For the tools examples? For testbeds?
  • It would mean they have to be run with cargo run --bin or cargo run -p.
    • This might be less confusing, because these programs are not intended for teaching users how to develop in Bevy and are not "examples" per se.
    • This might be more confusing, because it introduces another different way of building and running things in the repo.
  • It might give us more flexibility w.r.t how to configure and manage them.

Future Work

(out of scope for this PR)

• Refactor the existing "game" examples (that will stay under examples/games/) into multiple files to teach best practices and project structure.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[alice-i-cecile]

I'd like to call this out in the release notes: documentation improvements are really important too! Please feel free to steal from the contributor's guide or leave a short stub!