Show full program context when eye button is clicked in Hello World example - #147
Show full program context when eye button is clicked in Hello World example#147RowanTL wants to merge 1 commit into
Conversation
|
Here's a visual of what I changed: New docs: new_docs.mp4Old docs: old_docs.mp4 |
| # Snippets in this book are library code (cdylib entry points, #[godot_api] impls, ...) and | ||
| # depend on the `godot` crate, so none of them can run on play.rust-lang.org. Without this, | ||
| # mdbook silently wraps every Rust block in a hidden `fn main() { ... }`, which the "show | ||
| # hidden lines" eye icon then reveals as if it were real code. Explicit `# ` hidden lines | ||
| # still work as usual. |
There was a problem hiding this comment.
That's a lot of words used while shorter one-line sentence could do a job just fine.
| // Anchor names may be opened and closed more than once; mdbook concatenates the regions and | ||
| // hides everything in between. That is how a block can show e.g. the `impl` header and one | ||
| // method without the other methods. |
There was a problem hiding this comment.
why do you describe something which is included in mdbook documentation https://wofwca.github.io/mdBook/format/mdbook.html#including-portions-of-a-file?
There was a problem hiding this comment.
Sometimes I leave slop in. Planning to remove.
| // Complete source for the Hello World tutorial. Every code block in | ||
| // src/intro/hello-world.md includes one of the anchors below. |
There was a problem hiding this comment.
what does this comment is supposed to convey?
| // ANCHOR_END: physics-process | ||
| // In GDScript, this would be: | ||
| // rotation += angular_speed * delta | ||
|
|
||
| // ANCHOR: physics-process | ||
| // GDScript code: | ||
| // | ||
| // rotation += angular_speed * delta | ||
| // var velocity = Vector2.UP.rotated(rotation) * speed | ||
| // position += velocity * delta | ||
|
|
||
| let radians = (self.angular_speed * delta) as f32; | ||
| self.base_mut().rotate(radians); | ||
| // The 'rotate' method requires a f32, | ||
| // therefore we convert 'self.angular_speed * delta' which is a f64 to a f32 | ||
| // ANCHOR_END: rotate |
There was a problem hiding this comment.
these examples should be separate; while enlarged they are displayed as:
which is very confusing.
There was a problem hiding this comment.
Seems like the best way around this is two have two separate Rust files or foregoing the hidden lines feature on one of the blocks. lmk what you think.
There was a problem hiding this comment.
I think two files might be okay, people might want to copy-paste them
| // therefore we convert 'self.angular_speed * delta' which is a f64 to a f32 | ||
| } | ||
| } | ||
| {{#rustdoc_include code/hello-world.rs:rotate}} |
There was a problem hiding this comment.
Personally I would just inline this one example (or split existing one into two if somebody insists). Additionally, rotate section is misleading - the example showcases usage of virtual method physics_process.
and a small update can be made – for a long time one can use delta: f32 directly in *process methods.
There was a problem hiding this comment.
Will change rotate to something else. If you're okay with losing the hidden context here, I'd be okay with inlining too (unless you want to copy and paste the entirety of hello-world.rs into the readme just for it).
New to godot and haven't really ever contributed to a large codebase personally or professionally before. Thanks for the review!
2 participants
Why
When I read through a rust book, I like to click on the little eye icon to see how a block of code fits into the entirety of the program. I found myself confused after reading through the Hello World example.
Problem
The current behavior of the eye button wraps the block of code in a main function call. This is not verbose enough and confusing in my opinion. Also, none of the playground examples compile.
Proposed Changes
lib.rsfileMore details about the changes
The play button is removed by adding the block below to
book.tomlAs for showing code when the eye icon is pressed, I created a file at
src/intro/code/hello-world.rsthat has anchors placed in it, controlling what code is shown. I removed the linefn init(base: Base<Sprite2D>) -> Self { /* as before */ }from being mentioned as the user could simply click the eye and see the implementation. Finally, I added an admonish tip to click the eye before theRust entry pointblock.AI Usage
I used Claude Opus 5 in this PR. Claude stitched together the code blocks and placed most of the anchor points in
src/intro/code/hello-world.rs. I modified the anchor points to remain loyal to the original rust blocks.Testing
Using Godot 4.7.1, I saw
icon.svgmoving in a circle from the code insrc/intro/code/hello-world.rswhen running the scene. I have not tested whether theCustom Rust APIsblock functions.Final Notes
If anything could be changed, let me know.