Testing documentation examples #99

Vrixyz · 2024-05-23T09:01:25Z

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.
- a new folder templates_injected is created, containing all the templates with injected code,in order to play well with PUBLISH_MODE=0, so we can review templates on their aggregated page.
  - This also enables us to compare generated templates "easily", for example such as https://gist.github.com/Vrixyz/a8318e90ade070c197dd658cbc671b1d (as of 357ab22), generated with the script ./diff_with_branch.sh
- another folder inject_file/tmp_diff is created, containing diffs from template to injected files. Mostly for debug purposes, not sure if we keep it, I might turn this behaviour off by default
the ./generate_user_guides.sh script is updated to do the injection automatically.

Solution considerations

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

Migration fixes or modification details (long)

colliders:
- collider type modification: sensor component added/removed
- colliderposition: z position moved in 2d examples ; missing rparenthesis ; missing rangle
- colliders solver/group flags ( "Collision groups and solver groups" for bevy plugin is out of date #75 )
- ActiveCollisionTypes::KINEMATIC_FIXED -> KINEMATIC_STATIC
  - ⚠️ : TODO: rename STATIC to fixed in bevy_rapier
- ColliderFlagsComponent -> ActiveHooks
- RigidBody without GlobalTransform, with child ; causing runtime warning.
  - I added GlobalTransform
- Quat::IDENTIY -> Quat::IDENTITY
joints:
- local_anchor -> local_anchor1
- added colliders + SpatialBundle, maybe too verbose but more useful.
- Vector3::x_axis() -> Vec3::X (use bevy rather than na)
- useless mut 🤷
CharacterController:
- That collider optionally be attached to a rigid-body
- character_controller -> character_controllers
- to_radians() needs explicit type
- modify_character_controller_autostep -> modify_character_controller_up
- modify_character_controller_slopes -> read_character_controller_collisions
Scene queries:
- shapecasting max_toi now ShapeCastOptions
  - ⚠️ : would be neat to document those
  - ⚠️ : I'd appreciate an example to show how to retrieve the hit/normal in global space. (smth like globalTransform.TransformPoint/Direction)
    - ⚠️ : + wrong docs (https://docs.rs/bevy_rapier3d/latest/bevy_rapier3d/plugin/struct.RapierContext.html#method.cast_shape) ;
      also related discussion on discord: https://discord.com/channels/691052431525675048/1242987460288315425/1245383515953037424
- intersections_with_point takes an owned Vect ; (maybe a ref is better?)
- intersections*: a few borrow parameters are actually owned
- QueryFilter: IntersectionGroup -> CollisionGroup
  - + similar to ( "Collision groups and solver groups" for bevy plugin is out of date #75 )
- QueryFilter: rather than using (the complicated) userdata, I hooked up to a bevy query.
advanced collision detection
- collide handle -> ColliderHandle
- sample code to add the marker ActiveEvents::CONTACT_FORCE_EVENTS ?
- ⚠️ : check solo lines codes shared with rust/js, in bevy anyway: has_any_active_contact -> has_any_active_contacts
- manifold data -> .raw.data + direct properties (not function calls)
- contacts_with -> contact_pairs_with
- intersections_with -> intersection_pairs_with
- App::build -> App::new

Bugs:

⚠️ : pixels_per_meter doesn't work ?
⚠️ : CharacterController broken (with bevy)
grounded becomes sometimes false (Strange KinematicCharacterControllerOutput behaviour bevy_rapier#377)
update translation must be in FixedUpdate
examples lack a SpatialBundle or TransformBundle
doesn't work without a collider ? (maybe just needs a shape?)
2 characterController on top of one another end up blocked.
solver_contacts ref needed for borrow checker + function is actually a property.

Tutorial flow notes

My feeling over going through the bevy user guide is quite positive, as it's very precise, and useful to make sense of how it works together.

It might be bit more resembling to a reference than a "guide" though, with a vibe of "it will all make sense when you finish, promise".

Suggestions:

avoid code snippet which are `too isolated, prefer slightly more lines of code but usefulness.
- or now that we have "context" available, we could have less lines of code but better context
  - i.e.: avoid the redundant command.spawn for an insert ; not obligated to end lines with ;
  - maybe use highlight code from docusaurus ? https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting

Also, there's a lot of code shared withing this user guide, we might want to consider consolidating the crates documentation for reference, and link to those rather than re-implementing and maintaining our own rustdoc ?

Or study if we can apply some of ideas from https://diataxis.fr/

Vrixyz · 2024-05-23T09:04:05Z

.nvmrc

@@ -0,0 +1 @@
+v16.20.2


Not certain it's useful, but I wasn't sure which node version to use through yarn

Vrixyz · 2024-05-23T09:07:12Z

docs-examples/2d/bevy/examples/basic_sim2.rs

+        println!("Ball altitude: {}", transform.translation.y);
+    }
+}
+// DOCUSAURUS: stop basic_sim


for simplicity I chose to always have markers start/stop, even if we inject the whole file.

note: now its // DOCUSAURUS: basic_sim stop

docs-examples/3d/bevy/examples/rigid_bodies3.rs

docs-examples/2d/bevy/Cargo.lock

Vrixyz · 2024-05-24T18:35:59Z

yarn.lock

I think I wrongly ran npm update, this should probably be reverted

Vrixyz · 2024-05-29T20:13:29Z

generate_user_guides.sh


 cp -r docs/user_guides/templates/* docs/user_guides/rust/.
 cp -r docs/user_guides/templates/* docs/user_guides/bevy_plugin/.
 cp -r docs/user_guides/templates/* docs/user_guides/javascript/.

 find docs/user_guides/bevy_plugin/ -type f -print0 | xargs -0 gawk -i inplace -v RS='<rapier>[^<]*</rapier>' -v ORS= '1'
-find docs/user_guides/bevy_plugin/ -type f -print0 | xargs -0 gsed -i '/<rapier>/,/<\/rapier>/d'


these should be reverted

Still I'm curious if it's needed ; I tested from windows and mac and I didn't notice any major difference (but maybe the devil is in the details?)

Let’s keep your changes. Maybe there is something weird going on my end.

package.json

Vrixyz · 2024-05-29T20:16:25Z

docs-examples/inject_file/src/main.rs

+    // Trimming end for cross platform, on windows I had \r finishing result.
+    assert_eq!(result.trim_end(), "correct data1 1");


I'm curious about an explaination as to why I'm getting "\r" ; I believe my source file only has "\n" 🤔

I replaced all \r\n with \n ; I assume that won't be aproblem 🤷

docs-examples/inject_file/src/main.rs

inject_code_in_user_guides.sh

docs/user_guides/templates/character_controller_slopes.mdx

+ a few other injection fixes

… branch to branch)

….rs into fix_doc_examples_code_test

inject_code_in_user_guides.sh

sebcrozet

This looks fantastic, thank you!

Would it make sense if the <load ... /> substitution also added the '''rust backtics automatically?
Could we rename <load ... /> into <example ... />?

sebcrozet · 2024-05-31T13:57:13Z

generate_user_guides.sh


 cp -r docs/user_guides/templates/* docs/user_guides/rust/.
 cp -r docs/user_guides/templates/* docs/user_guides/bevy_plugin/.
 cp -r docs/user_guides/templates/* docs/user_guides/javascript/.

 find docs/user_guides/bevy_plugin/ -type f -print0 | xargs -0 gawk -i inplace -v RS='<rapier>[^<]*</rapier>' -v ORS= '1'
-find docs/user_guides/bevy_plugin/ -type f -print0 | xargs -0 gsed -i '/<rapier>/,/<\/rapier>/d'


Let’s keep your changes. Maybe there is something weird going on my end.

Vrixyz · 2024-05-31T14:07:40Z

generate_user_guides.sh

 cp -r docs/user_guides/templates/* docs/user_guides/rust/.
 cp -r docs/user_guides/templates/* docs/user_guides/bevy_plugin/.
 cp -r docs/user_guides/templates/* docs/user_guides/javascript/.


should load injected_templates ?

Vrixyz · 2024-06-03T08:36:49Z

Would it make sense if the <load ... /> substitution also added the '''rust backtics automatically?

I decided against because the substitution is language agnostics, I'll want to use the same code for javascript injections. It also allows to add other code snippet if needs be. I'm not feeling too opinionated in this though.

Could we rename <load ... /> into <example ... />?

I have no strong opinion on this either ; this injection could work to load another markdown file though (it's probably not a good idea as there are better tools), but I felt "load" conveys better its inner working. Alternatives considered were "file", "inject"...

….rs into fix_doc_examples_code_test

rlidwka · 2024-09-09T14:54:07Z

docs-examples/3d/bevy/examples/basic_sim3.rs

+    for mut transform in positions.iter_mut() {
+        dbg!(transform.rotation.to_axis_angle());
+        transform.rotation = Quat::from_rotation_z(270_f32.to_radians());
+        //println!("Ball altitude: {}", transform.translation.y);


@Vrixyz this doesn't seem to print ball altitude anymore.

I suspect that debug code was put here then forgotten about.

Thanks! not sure what went wrong about this indeed :o

fix: fix ball altitude not being displayed anymore from basic_sim3 example… #118

Vrixyz added 4 commits May 17, 2024 10:37

some testing of rapier.rs snippets (bevy_rapier until rigid body forces)

31fe00c

attempt to use magic comment failed

46988c0

wip workspace + replace in files

8f8594d

update generate_user_guides script to include code injection

ecf7919

Vrixyz force-pushed the fix_doc_examples_code_test branch from fbf87d7 to e5c689c Compare May 23, 2024 09:05

removed tests on magicComments

86e9456

Vrixyz force-pushed the fix_doc_examples_code_test branch from e5c689c to 86e9456 Compare May 23, 2024 09:10

Vrixyz mentioned this pull request May 24, 2024

contact_pair.has_any_active_contact() should be contact_pair.has_any_active_contacts() in the documentation? #101

Closed

Vrixyz commented May 24, 2024

View reviewed changes

copied example code into separate file: rigidbodies

3654629

Vrixyz mentioned this pull request May 27, 2024

"Collision groups and solver groups" for bevy plugin is out of date #75

Closed

Vrixyz added 12 commits May 27, 2024 11:57

add colliders page code snippets

8e0c5b9

minor text fixes

d63f3c8

WIP: generation for first few sections

4f795b9

generate templates_injected

3b73221

add joints example code

b7698e3

character_controller code snippets

f466df3

fixed missing word

4051a3f

add injection for character controller

1992d14

joints doc injection with code snippets

7688415

added test to inject script

6083260

fix a some incorrected injected files

58bb0fe

code snippet for scene queries

79491c8

Vrixyz commented May 29, 2024

View reviewed changes

docs/user_guides/templates/character_controller_slopes.mdx Outdated Show resolved Hide resolved

Vrixyz added 5 commits May 29, 2024 22:52

chmod+x inject script

0493288

fixed wrong injections due to single '

5e0f29a

+ a few other injection fixes

add script to better see the diff with master (and going forward from…

85634ac

… branch to branch)

still more fixes + tests

f2f3050

slightly better output

a8eb8ea

Vrixyz added 4 commits May 30, 2024 13:00

wip advanced_collision_detection

6104e1e

code snippets for advanced_collision_detection

d807303

last injections for bevy implemented

0da4485

Merge branch 'fix_doc_examples_code_test' of github.com:Vrixyz/rapier…

7a13f0f

….rs into fix_doc_examples_code_test

Vrixyz marked this pull request as ready for review May 30, 2024 13:59

Vrixyz force-pushed the fix_doc_examples_code_test branch from c97db84 to 284b9d3 Compare May 30, 2024 14:02

CI test

08801ef

Vrixyz force-pushed the fix_doc_examples_code_test branch from 284b9d3 to 08801ef Compare May 30, 2024 14:10

Vrixyz commented May 30, 2024

View reviewed changes

inject_code_in_user_guides.sh Outdated Show resolved Hide resolved

Vrixyz added 4 commits May 31, 2024 12:03

self review

0d60633

remove extraneous (nested) injection marker lines

94962e5

fixed wrong marker

93cceaa

more correct diff script folder paths

619768b

Vrixyz requested a review from sebcrozet May 31, 2024 10:26

Vrixyz mentioned this pull request May 31, 2024

Getting Started webpage: instantiates BroadPhase trait #102

Closed

sebcrozet approved these changes May 31, 2024

View reviewed changes

Vrixyz commented May 31, 2024

View reviewed changes

Vrixyz added 6 commits June 3, 2024 10:47

generate script uses correct folder as source of truth

2c0a48b

unindent injected files

f9116d8

fix indentation handling with empty lines

0d63143

more condensed readme

4c4b8c5

Merge branch 'fix_doc_examples_code_test' of github.com:Vrixyz/rapier…

df99d35

….rs into fix_doc_examples_code_test

fix remove indentation + no extraneous lines

357ab22

Vrixyz requested a review from sebcrozet June 3, 2024 11:37

lower node version requirements

ad3a37c

Vrixyz merged commit 160f573 into dimforge:master Jun 3, 2024

Vrixyz mentioned this pull request Jun 4, 2024

Ci rust code snippets #104

Merged

rlidwka reviewed Sep 9, 2024

View reviewed changes

Vrixyz mentioned this pull request Sep 9, 2024

fix ball altitude not being displayed anymore from basic_sim3 example… #118

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Testing documentation examples #99

Testing documentation examples #99

Vrixyz commented May 23, 2024 •

edited

Loading

Vrixyz May 23, 2024

Vrixyz May 23, 2024

Vrixyz May 31, 2024

Vrixyz May 24, 2024

Vrixyz May 29, 2024

Vrixyz May 30, 2024

sebcrozet May 31, 2024 •

edited

Loading

Vrixyz May 29, 2024

Vrixyz May 31, 2024

sebcrozet left a comment

sebcrozet May 31, 2024 •

edited

Loading

Vrixyz May 31, 2024 •

edited

Loading

Vrixyz commented Jun 3, 2024 •

edited

Loading

rlidwka Sep 9, 2024

Vrixyz Sep 9, 2024

Vrixyz Sep 9, 2024

		// Trimming end for cross platform, on windows I had \r finishing result.
		assert_eq!(result.trim_end(), "correct data1 1");

		@@ -0,0 +1 @@
		v16.20.2

Testing documentation examples #99

Testing documentation examples #99

Conversation

Vrixyz commented May 23, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sebcrozet May 31, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sebcrozet left a comment

Choose a reason for hiding this comment

sebcrozet May 31, 2024 • edited Loading

Choose a reason for hiding this comment

Vrixyz May 31, 2024 • edited Loading

Choose a reason for hiding this comment

Vrixyz commented Jun 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vrixyz commented May 23, 2024 •

edited

Loading

sebcrozet May 31, 2024 •

edited

Loading

sebcrozet May 31, 2024 •

edited

Loading

Vrixyz May 31, 2024 •

edited

Loading

Vrixyz commented Jun 3, 2024 •

edited

Loading