rapier.rs icon indicating copy to clipboard operation
rapier.rs copied to clipboard

Testing documentation examples

Open ThierryBerger opened this issue 1 year ago • 0 comments

Testing all examples is very time consuming, and checking them all by hand is error prone. Having an easy way to test them would help.

What this PR does:

  • create a new workspace docs-examples, containing Rust examples (I didn't start to work on javascript)
    • We can easily test that all examples compile through cargo check --examples
  • For the templates: defines a new <load> tag (in the mindset of <bevy>, <rust>, <js>...
    • the new workspace docs-examples also contains a crate inject_code, which is responsible to parse a file, detect the load tag, and inject the code inside, keeping only relevant marked lines.
  • the ./generate_user_guides.sh script is updated to do all that automatically.

I'd like to validate that approach before migrating all code examples to it.

Thoughts: It's a bit unfortunate that it creates an indirection when editing the docs (we have to go check the content of the file linked), but the alternatives being:

  • 🔴 Don't change anything, and risk errors at each new releases
  • 🔴 Inverse the source of truth: create a rust project from the documentation. It's a bit more complicated to do, and risks having very big files for the doc

ThierryBerger avatar May 23 '24 09:05 ThierryBerger