setup xtask infra for cheatsheets #159

miguelraz · 2024-06-10T22:21:33Z

Problem:

Making cheatsheets like "From Python to Rust" and friends is going to be a maintainability nightmare as training-materials grows, changes ownership, etc., over time. This was raised as a concern in #148 and this PR seeks to fix that.

Proposed solution:

Setup a xtask style workflow where we

call cargo xtask make-cheatsheet python at the root folder
scrape Markdown headers in SUMMARY..md and segment topics by Rust Fundamentals, Applied Rust and Advanced Rust
write out to src/python-cheatsheet.md if it doesn't exist
if it does exist, check that it in sync: all headers in python-cheatsheet.md are in the appropriate sections, in order, and none are missing.

The code is (I think) defensive to spare future pain for someone else looking at this code ~~(myself in a few months)~~.

This PR only sets up the infrastructure but doesn't add any cheatsheets themselves - I'll file a separate PR with a basic Julia cheatsheet once this lands to separate concerns.

Current functionality:

❯ cargo xtask make-cheatsheet python
   Compiling xtask v0.1.0 (C:\Users\mrg\work\rust-training\xtask)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.10s
     Running `target\debug\xtask.exe make-cheatsheet python`
Cheatsheat for python written at ./training-slides/src/python-cheatsheet.md

❯ cat .\training-slides\src\python-cheatsheet.md
# Rust Fundamentals
## Overview
## Installation
## Basic Types
## Control Flow
## Compound Types
## Ownership and Borrowing
## Error Handling
## Collections
## Iterators
## Imports and Modules
## Good Design Practices

# Applied Rust
## Methods and Traits
## Rust I/O Traits
## Generics
## Lifetimes
## Cargo Workspaces
## Heap Allocation (Box and Rc)
## Shared Mutability (Cell, RefCell)
## Thread Safety (Send/Sync, Arc, Mutex)
## Closures and the Fn/FnOnce/FnMut traits
## Spawning Threads and Scoped Threads

# Advanced Rust
## Advanced Strings
## Debugging Rust
## Dependency Management with Cargo
## Deref Coercions
## Design Patterns
## Documentation
## Drop, Panic and Abort
## Dynamic Dispatch
## Macros
## Property Testing
## Rust Projects Build Time
## Send and Sync
## Serde
## Testing
## The stdlib
## Using Cargo
## Using Types to encode State
## WASM

❯ cargo xtask make-cheatsheet python
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
     Running `target\debug\xtask.exe make-cheatsheet python`
File python-cheatsheet.md already exists - checking it's in sync
Neat! python-cheatsheet.md is in sync

rust-training on  xtask-cheatsheet [$?] via 🦀 v1.78.0
❯ cargo xtask test-cheatsheet python
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.04s
     Running `target\debug\xtask.exe test-cheatsheet python`
Neat! python-cheatsheet.md is in sync

cloudflare-workers-and-pages · 2024-06-13T00:29:58Z

Deploying ferrous-systems-rust-training with Cloudflare Pages

Latest commit:	`d85c40f`
Status:	✅ Deploy successful!
Preview URL:	https://84f9496e.ferrous-systems-rust-training.pages.dev
Branch Preview URL:	https://xtask-cheatsheet.ferrous-systems-rust-training.pages.dev

View logs

jonathanpallant · 2024-06-13T08:12:13Z

Could we add a few words (here, or in a README) about how the cheatsheets work - to save having to read and understand the source code?

jonathanpallant · 2024-06-13T08:13:36Z

Also, it needs a rebase on main to fix the CloudFlare CI failure, and some thought about the workspaces to fix the GHA CI failure.

…xtra sections

miguelraz · 2024-06-13T14:40:19Z

@jonathanpallant

added a README.md
rebased to main to have Cloudflare deploy passing
fixed workspace issue by adding a exclude = ["examples/"] array to the Cargo.toml and CI is happy

xtask/README.md

jonathanpallant · 2024-07-01T08:51:58Z

xtask/README.md

+As `training-material` grows and changes, maintenance could be a nightmare. We basically don't want to be in the business of remember that a certain slide got reordered or moved from one section to another and thus needs changing in all the cheathseets as well. Therefore, this tool seeks to alleviate that with the following workflow:
+
+* call `cargo xtask make-cheatsheet python` at the root folder
+* scrape Markdown headers in `SUMMARY.md` and segment topics by `Rust Fundamentals`, `Applied Rust` and `Advanced Rust`


Who does this - the user or the tool? Because step 1 in this list is something the user has to do.

jonathanpallant · 2024-07-01T08:53:42Z

xtask/src/main.rs

+
+    // first arg is the name of the executable; skip it
+    let args = env::args().skip(1).collect::<Vec<_>>();
+    let args = args.iter().map(|arg| &arg[..]).collect::<Vec<_>>();


What is this line for? args is already a Vec<String> right?

jonathanpallant · 2024-07-01T08:54:06Z

xtask/src/main.rs

+    let args = env::args().skip(1).collect::<Vec<_>>();
+    let args = args.iter().map(|arg| &arg[..]).collect::<Vec<_>>();
+
+    let langs = vec!["python", "go", "cpp", "swift", "java", "julia", "c"];


Could be an array?

jonathanpallant · 2024-07-01T08:54:22Z

xtask/src/main.rs

+    let langs = vec!["python", "go", "cpp", "swift", "java", "julia", "c"];
+
+    if !langs.contains(&args[1]) {
+        panic!("{} is not a valid language name. \nExpected one of: python, go, cpp, swift, java, julia, c", &args[1]);


I'd print the lang list in the panic so it doesn't get out of sync.

jonathanpallant · 2024-07-01T08:54:55Z

xtask/src/main.rs

+        ["test-cheatsheet", lang] => tasks::test_cheatsheet(lang),
+        _ => {
+            eprintln!(
+                "cargo xtask


Perhaps move to a static HELP_TEXT: &'static str = "..." so it doesn't confuse the formatting of the match expression.

jonathanpallant · 2024-07-01T08:56:06Z

xtask/src/tasks.rs

+}
+
+#[test]
+fn test_get_slide_name() {


Tests should go in a #[cfg(test)] mod test { ... }

jonathanpallant · 2024-07-01T08:58:26Z

xtask/src/tasks.rs

+        panic!("YOUR LAST_HEADER is not part of the text input. CHECK your `SUMMARY.md` for {LAST_HEADER}");
+    }
+
+    let first_header = text.find(INITIAL_HEADER).unwrap();


You can handle the error here rather than having a separate contains check which might get isolated from this line.

let Some(first_header) = text.find(INITIAL_HEADER) else { panic!("Could not find the initial header {INITIAL_HEADER:?}. Check your `SUMMARY.md`"); }

jonathanpallant · 2024-07-01T08:59:57Z

xtask/src/tasks.rs

+}
+
+#[test]
+fn test_focus_regions() {


Tests should go in a #[cfg(test)] mod test { ... }

jonathanpallant · 2024-07-01T09:00:02Z

xtask/src/tasks.rs

+}
+
+#[test]
+fn test_extract_slides() {


Tests should go in a #[cfg(test)] mod test { ... }

jonathanpallant · 2024-07-01T09:02:47Z

OK, I think this tool makes sense. I had some minor points about the program itself, but I also think we should be running the unit tests in CI, and testing our cheat-sheets in CI.

Co-authored-by: Jonathan Pallant <[email protected]>

jonathanpallant · 2024-07-03T08:47:39Z

re-assign to me when you're ready, thanks!

miguelraz mentioned this pull request Jun 13, 2024

Language refreshers aka "Coming from Python" cheatsheets #148

Closed

miguelraz marked this pull request as ready for review June 13, 2024 01:41

miguelraz added 11 commits June 13, 2024 08:05

setup xtask infra for cheatsheets

328a963

setup xtask infra for cheatsheets

1357aea

almost working extract_slides

ead0e8f

working get_slide_name

5c04043

working utility functions for make_cheatseet

1a4b33e

working make_cheatsheet writing into file

3d9c2de

deny warnings in xtask

0bcc288

error when not giving an appropriate language

fbe4766

working test-cheatsheet

33e8014

take out cruft

4d34c0f

add README.md for how cheatsheets work

ddd8c18

miguelraz force-pushed the xtask-cheatsheet branch from e33892a to ddd8c18 Compare June 13, 2024 14:06

miguelraz added 3 commits June 13, 2024 08:10

exclude example-code/ from workspace

ce4e707

exclude example-code from workspace

54067a4

add README note on additional sections at the end and code to allow e…

ab2ef80

…xtra sections

jonathanpallant reviewed Jul 1, 2024

View reviewed changes

xtask/README.md Outdated Show resolved Hide resolved

jonathanpallant reviewed Jul 1, 2024

View reviewed changes

xtask/src/tasks.rs

}

#[test]

fn test_get_slide_name() {

Copy link

Member

jonathanpallant Jul 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests should go in a #[cfg(test)] mod test { ... }

jonathanpallant reviewed Jul 1, 2024

View reviewed changes

xtask/src/tasks.rs

}

#[test]

fn test_focus_regions() {

Copy link

Member

jonathanpallant Jul 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests should go in a #[cfg(test)] mod test { ... }

jonathanpallant reviewed Jul 1, 2024

View reviewed changes

xtask/src/tasks.rs

}

#[test]

fn test_extract_slides() {

Copy link

Member

jonathanpallant Jul 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests should go in a #[cfg(test)] mod test { ... }

Update xtask/README.md

d85c40f

Co-authored-by: Jonathan Pallant <[email protected]>

jonathanpallant assigned miguelraz Jul 1, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

setup xtask infra for cheatsheets #159

setup xtask infra for cheatsheets #159

miguelraz commented Jun 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 13, 2024 •

edited

Loading

jonathanpallant commented Jun 13, 2024

jonathanpallant commented Jun 13, 2024

miguelraz commented Jun 13, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

miguelraz Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant Jul 1, 2024

jonathanpallant commented Jul 1, 2024

jonathanpallant commented Jul 3, 2024

setup xtask infra for cheatsheets #159

Are you sure you want to change the base?

setup xtask infra for cheatsheets #159

Conversation

miguelraz commented Jun 10, 2024 • edited Loading

Problem:

Proposed solution:

cloudflare-workers-and-pages bot commented Jun 13, 2024 • edited Loading

Deploying ferrous-systems-rust-training with Cloudflare Pages

jonathanpallant commented Jun 13, 2024

jonathanpallant commented Jun 13, 2024

miguelraz commented Jun 13, 2024

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

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

jonathanpallant commented Jul 1, 2024

jonathanpallant commented Jul 3, 2024

miguelraz commented Jun 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 13, 2024 •

edited

Loading