rust-training icon indicating copy to clipboard operation
rust-training copied to clipboard

setup xtask infra for cheatsheets

Open miguelraz opened this issue 8 months ago • 6 comments

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

miguelraz avatar Jun 10 '24 22:06 miguelraz