-
Notifications
You must be signed in to change notification settings - Fork 382
Enhance learning material code examples validation and formatting #1578
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Enhance learning material code examples validation and formatting #1578
Conversation
Feels nicer to use compared to example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Delightful! Really pleased to see this working, and I think this is a reasonable approach.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yay, I'm so happy this is finally happening! Thank you for your hard work :D
(I have a few nits, but nothing blocking.)
`./validate_examples.sh` | ||
|
||
>[!TIP] | ||
> The bash script can be called from any directory! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🥳
Co-authored-by: BD103 <[email protected]>
It does not make sense to version the project in this situation.
This is to prevent accidental calls of `cargo publish` having adverse effects.
Showcases how to write the learning-code-example's examples using the tools provided.
This way there is no ambiguities regarding the naming scheme for versioned, or staged progression, based example files.
Objective
Part of #265
Fixes #279
As it stands code snippets used in the learning materials are not formatted and are currently only checked / validated by
code-validation
which is a generally fragile, and at times frustrating, tool.Solution
This PR removes the
code-validation
tool and supplants it withlearning-code-examples
which is a Cargo project without asrc/
folder which stores the learning material code examples in theexamples/
directory. From here we can runcargo check --examples
,cargo clippy --examples
, and most importantlycargo fmt --check
to validate and format the learning material code examples. Tho for ease of use it also supplies avalidate_examples.sh
script which runs all three of those commands on the examples.The examples within have
// ANCHOR: name
,// ANCHOR_END: name
and// HIDE
to create the code snippets used in the pages.The
file_code_block
shortcode also got refactored to accommodate this and is now the primary way to use code block examples in the learning materials.The Quick Start Guide has been converted to use this tool as well.
Note
See the
learning-code-examples/README.md
for full usage details.Note
This tool may also supplant
write-rust-doc-lines
, but I am unsure ifwrite-rust-doc-lines
impacts only the learning material code blocks, or if we also use it in the migration guides and other places in the site's content.Testing
Run
zola serve
to see the results of the snippets being pulled in.Run
./validate_examples.sh
to see the code examples be confirmed as running. (This actually helped spot that the plugin-development generic plugin example was non-functional; now it should work).