Create Rust tutorials feature branch#1
Merged
Conversation
Create comprehensive documentation for Claude Code including: - Multi-instance Docusaurus architecture explanation - Development commands and workflows - Blog thumbnail generation system - Content organization and guidelines - Common tasks and technical configuration This file helps future AI assistants understand the codebase structure and work more effectively with the Vietnamese ELI5 tutorial content.
Create detailed roadmap for Rust tutorials with ~110 articles covering: 🟢 Basics (20 articles): Installation, cargo, variables, data types, I/O 🟡 Intermediate (18 articles): Control flow, collections, functions, strings 🔴 Advanced (42 articles): Ownership, borrowing, lifetimes, traits, async 🎮 Projects (12 articles): CLI tools, web server, chat app, REST API 💪 Practice (7 articles): Exercises for each major topic 📚 Reference (8 articles): Cheatsheets, common crates, best practices 📖 Glossary (4 articles): Rust-specific and general programming terms Key features: - Uses "safety equipment" (đồ bảo hộ an toàn) metaphor throughout - Vietnamese ELI5 approach for beginners - Structured progression from beginner to advanced - Real-world projects at each level - 12-week implementation roadmap - Best practices for writing ELI5 content Based on research from official Rust book, Zero To Mastery, and community resources, adapted for Vietnamese learners.
Create comprehensive Rust documentation foundation: 1. intro.md - Complete introduction to Rust - Safety equipment metaphor (đồ bảo hộ an toàn) - Why Rust is special: safety, speed, concurrency - Comparison with Python, Java, C++, Go - Who uses Rust (Mozilla, Discord, Dropbox, etc.) - Learning roadmap with Mermaid diagram - ELI5 explanations throughout 2. basics/what-is-rust.md - Rust history and fundamentals - Origin story (Graydon Hoare, 2006) - Rust vs C/C++, Go, Python with code examples - Memory safety explained with Vietnamese analogies - Why learn Rust: jobs, deep knowledge, confident code - Stack Overflow, GitHub, TIOBE statistics - Use cases: systems, web, CLI, blockchain, games 3. basics/installing-rust.md - Installation guide - Step-by-step for Windows, macOS, Linux - Rustup, cargo, rustc setup - VS Code + rust-analyzer configuration - RustRover alternative - Troubleshooting common issues - Additional tools: rustfmt, clippy, docs All content follows ELI5 Vietnamese approach with: - Simple analogies (xe máy, mũ bảo hiểm, etc.) - Encouraging tone about compiler errors - Real-world Vietnamese examples - Code examples with comments - Clear next steps and learning paths
Add 3 comprehensive Rust basics tutorials: 1. basics/printing-output.md - Printf and formatting - println!, print!, eprintln! macros - Format strings with placeholders - Debug vs Display formatting - Alignment and padding - Number formatting - Real-world examples (menus, tables, progress bars) - format! macro for string creation - Escape characters and raw strings - 3 practice exercises 2. basics/comments.md - Writing comments - Line comments (//) and block comments (/* */) - Doc comments (/// and //!) - Best practices for good comments - When to use comments vs self-documenting code - TODO, FIXME, NOTE conventions - Markdown in doc comments - cargo doc for documentation - 3 practice exercises 3. basics/variables-and-mutability.md - Variables and mut - Immutable by default concept - let vs let mut - Why immutability is good (safety, clarity, performance) - Type annotations and inference - Constants with const - Shadowing and transformations - Best practices for choosing mut - Comparison with Python, JavaScript - 4 practice exercises Updated sidebars-rust.js with 3 new articles. All content maintains ELI5 Vietnamese approach with safety equipment metaphor.
Add 3 fundamental Rust basics tutorials: 1. basics/data-types.md - Data types fundamentals - Integers: i8-i128, u8-u128, signed vs unsigned - Floats: f32 vs f64, precision, special values - Boolean: true/false, 1 byte - Character: Unicode support, 4 bytes - Type conversion with as keyword - Overflow/underflow handling - Best practices for choosing types - 3 practice exercises including BMI calculator 2. basics/strings-basics.md - String vs &str - String literals (&str) and owned String - Memory layout: stack vs heap - Ownership and borrowing with strings - Conversion: to_string(), String::from(), & - String manipulation: push, push_str, concat - format! macro for string creation - UTF-8 and why indexing doesn't work - chars() and bytes() iteration - Best practices for parameters and returns - 3 practice exercises 3. basics/arithmetic-operations.md - Math operations - Basic operations: +, -, *, /, % - Integer vs float division - Type casting with as - Compound assignments: +=, -=, etc. - Operator precedence - Math methods: pow, sqrt, abs, min, max - Overflow handling: checked, saturating, wrapping - Division by zero safety - 4 practice exercises (calculator, temp conversion, tip, area) Updated sidebars-rust.js with 3 new articles (10 total now). All content maintains ELI5 Vietnamese approach.
Completed three foundational tutorials: - boolean-and-logic.md: Comparison and logical operators - input-output.md: Reading user input and parsing - error-basics.md: Understanding and debugging compiler errors This completes the core basics section with 13 comprehensive articles.
This reverts commit 84a91e5.
Added two intermediate control flow tutorials: - if-else.md: Conditional statements with if/else if/else - match.md: Pattern matching and exhaustive checking Updated sidebar with new Intermediate section (🟡 Trung Bình Thú Vị).
Added three comprehensive loop tutorials: - loop-basic.md: Infinite loops with break, continue, labels - while-loop.md: Conditional loops with while - for-loop.md: Iterating over ranges, arrays, vectors Covers iter(), iter_mut(), into_iter(), enumerate(), rev(). Updated sidebar with loop section.
Added three comprehensive collection tutorials: - arrays.md: Fixed-size arrays with slicing and iteration - vectors.md: Dynamic Vec<T> with push, pop, insert, remove - tuples.md: Multi-type tuples with destructuring and access Covers collection methods, when to use each type, and practical examples. Updated sidebar with collections section.
Added three comprehensive function tutorials: - functions-basics.md: Defining functions, parameters, return values, expressions vs statements - function-parameters.md: Pass by value/reference, borrowing, ownership with parameters - closures.md: Anonymous functions, capturing environment, using with iterators Covers function fundamentals, parameter patterns, and closure usage. Updated sidebar with functions section.
Added two comprehensive string manipulation tutorials: - string-methods.md: len, is_empty, to_uppercase/lowercase, trim, split, concat, format! - string-slicing.md: UTF-8 handling, chars(), bytes(), safe string indexing Completes Intermediate section with 13/13 articles. Covers string manipulation and safe UTF-8 handling.
Added three core Rust concepts starting the Advanced section: - ownership-basics.md: Three ownership rules, move semantics, scope, drop - borrowing.md: References (&T and &mut T), immutable/mutable borrowing rules - slices.md: String slices (&str) and array slices (&[T]) Updated sidebars-rust.js with new Advanced section. Covers Rust's unique memory management model with safety guarantees.
Added lifetimes.md covering:
- Lifetime annotations ('a, 'b, 'static)
- Lifetimes in functions and structs
- Lifetime elision rules
- Multiple lifetimes and practical examples
Updated sidebars-rust.js to include lifetimes tutorial.
Added three tutorials on custom types: - structs-basics.md: Defining structs, creating instances, field access, tuple structs - struct-methods.md: Methods with &self/&mut self/self, associated functions, method chaining - enums.md: Enum variants with data, pattern matching, Option/Result preview Updated sidebars-rust.js with new tutorials. Covers fundamental custom types in Rust.
Added error handling fundamentals: - option.md: Option<T> for nullable values, Some/None, unwrap methods, map/and_then - result.md: Result<T, E> for fallible operations, Ok/Err, ? operator, custom errors Updated sidebars-rust.js with new tutorials. Covers Rust's approach to error handling without null or exceptions.
Marked as completed: - Ownership fundamentals (ownership-basics, borrowing, slices, lifetimes) - Structs and Enums (structs-basics, struct-methods, enums) - Error handling basics (option, result) Total: 9 tutorials completed in Advanced section.
Marked as completed: - Basics section: 13 tutorials (what-is-rust through error-basics) - Intermediate section: 13 tutorials (if-else through string-slicing) - Advanced section: 9 tutorials (ownership through result) Total: 35 tutorials completed across all sections.
Added error handling best practices: - error-handling-advanced.md: panic! vs Result, custom errors, propagating with ? - thiserror-anyhow.md: thiserror for libraries, anyhow for applications Updated sidebars-rust.js and rust-tuts-plan.md. Covers professional error handling patterns in Rust.
Added three tutorials on generic programming and traits: - generics.md: Generic functions, structs, enums, trait bounds, monomorphization - traits.md: Defining traits, implementing traits, trait bounds, default implementations - trait-objects.md: Dynamic dispatch with dyn Trait, object safety Updated sidebars-rust.js and rust-tuts-plan.md. Covers core concepts of polymorphism in Rust.
Added three tutorials on code organization: - modules.md: Module system, pub visibility, nested modules, file-based modules - packages-crates.md: Binary vs library crates, workspaces, dependencies, publishing - use-and-paths.md: use keyword, absolute/relative paths, pub use, import patterns Updated sidebars-rust.js and rust-tuts-plan.md. Covers Rust's module system and project structure.
Batch 18 - Collections Nâng Cao Added comprehensive Vietnamese tutorials covering: - HashMap: Key-value storage with O(1) operations * Creating HashMaps from scratch and collections * Insert, get, remove, contains operations * Entry API for efficient updates * Iteration patterns * Real-world examples: user database, word frequency, cache, config - HashSet: Unique value collections * Creating sets and converting from vectors * Insert, contains, remove operations * Set operations: union, intersection, difference, symmetric difference * Subset/superset/disjoint checks * Practical uses: deduplication, visited tracking, tags, permissions Both tutorials follow ELI5 approach with Vietnamese life metaphors, extensive code examples, practice exercises, and summary tables. Updated: - sidebars-rust.js: Added hashmap and hashset to Advanced navigation - rust-tuts-plan.md: Marked both tutorials as completed [x]
Batch 19 - Iterators Added detailed Vietnamese tutorials covering: - Iterators: Core iterator functionality * Iterator trait and how it works * Three types: iter(), iter_mut(), into_iter() * Transform with map() and filter() * Aggregate with fold(), sum(), count(), min/max * Lazy evaluation and performance benefits * Real-world examples: user data processing, text processing, statistics - Iterator Adapters: Advanced iterator methods * enumerate() for adding indices * zip() for combining iterators * take(), skip() for limiting and pagination * take_while(), skip_while() for conditional iteration * chain() for concatenating iterators * flatten() and flat_map() for nested structures * Custom iterators with Iterator trait implementation * Practical examples: CSV processing, pagination, merge sorted lists, matrix ops Both tutorials follow ELI5 approach with "assembly line" metaphor, extensive code examples (40+ examples), practice exercises, and comprehensive comparison tables between iterator methods and traditional loops. Updated: - sidebars-rust.js: Added iterators and iterator-adapters to Advanced nav - rust-tuts-plan.md: Marked both iterator tutorials as completed [x]
Batch 20 - Smart Pointers
Added comprehensive Vietnamese tutorials covering:
- Box: Heap allocation and smart pointers
* Stack vs Heap comparison
* When to use Box: recursive types, large data, trait objects
* Linked list and binary tree examples
* Deref trait and deref coercion
* Box vs references comparison
* Real-world examples: tree structures, dynamic dispatch, large structs
- Rc and Arc: Reference counting for shared ownership
* Rc<T> for single-threaded shared ownership
* Arc<T> for thread-safe shared ownership
* Strong and weak reference counting
* Weak<T> to prevent memory leaks from reference cycles
* Rc vs Arc performance comparison
* Real-world examples: shared config, graph traversal, observer pattern, cache
- RefCell: Interior mutability pattern
* Interior mutability concept
* Runtime borrow checking with borrow() and borrow_mut()
* Rc<RefCell<T>> pattern for shared mutable state
* try_borrow() for safe borrowing
* Cell vs RefCell vs Mutex comparison
* Real-world examples: mock objects, trees with parent refs, cache stats, observer
All tutorials follow ELI5 approach with Vietnamese metaphors ("storage warehouse",
"shared documents", "smart safe"), extensive code examples (50+ examples),
practice exercises, and comprehensive comparison tables.
Updated:
- sidebars-rust.js: Added box, rc-arc, refcell to Advanced navigation
- rust-tuts-plan.md: Marked all Smart Pointers tutorials as completed [x]
…ed State)
Batch 21 - Concurrency
Added comprehensive Vietnamese tutorials covering:
- Threads: Multi-threaded programming basics
* Creating threads with thread::spawn
* Joining threads and receiving results
* Move closures for ownership transfer
* Arc for sharing data across threads
* Thread safety with Send and Sync traits
* Thread naming and configuration with Builder
* Real-world examples: parallel computation, worker pool, map-reduce, timeout
- Message Passing: Communication between threads
* mpsc channels (multiple producer, single consumer)
* Sending and receiving messages
* Blocking recv() vs non-blocking try_recv()
* Multiple producers with clone()
* Bounded vs unbounded channels (sync_channel)
* Real-world examples: task queue, producer-consumer, result collector, pipeline, request-response
- Shared State: Mutex and RwLock for mutable access
* Mutex<T> for exclusive access
* Arc<Mutex<T>> pattern for shared mutable state
* RwLock<T> for multiple readers or single writer
* Avoiding deadlocks with consistent lock ordering
* try_lock() for non-blocking access
* Mutex vs RwLock vs Channels comparison
* Real-world examples: shared counter, thread-safe cache, job queue, bank account
All tutorials follow ELI5 approach with Vietnamese metaphors ("restaurant staff",
"postal system", "meeting room with lock"), extensive code examples (60+ examples),
practice exercises, and comprehensive comparison tables.
Updated:
- sidebars-rust.js: Added threads, message-passing, shared-state to Advanced nav
- rust-tuts-plan.md: Marked all Concurrency tutorials as completed [x]
Batch 22 - Async Programming
Added comprehensive Vietnamese tutorials covering:
- Async/Await Basics: Fundamentals of asynchronous programming
* Async vs sync programming concepts
* async fn and .await keyword
* Futures trait and lazy evaluation
* Concurrent execution with tokio::join!
* Spawning tasks with tokio::spawn
* Async vs threads comparison
* Blocking vs non-blocking code
* Real-world examples: API calls, timeouts, select, concurrent processing
- Tokio Runtime: Production async runtime
* Setup and configuration in Cargo.toml
* #[tokio::main] macro and flavors
* Tokio tasks and spawning
* Time utilities: sleep, interval, timeout, Instant
* Async I/O: reading/writing files
* Synchronization: Mutex, RwLock, mpsc, oneshot
* Real-world examples: HTTP server, parallel file processing, rate limiter,
worker pool, retry pattern, fan-out/fan-in
* Error handling patterns
All tutorials follow ELI5 approach with Vietnamese metaphors ("restaurant service",
"task scheduling"), extensive code examples (50+ examples), practice exercises,
and comprehensive comparison tables (async vs threads, Tokio modules).
Updated:
- sidebars-rust.js: Added async-basics and async-tokio to Advanced navigation
- rust-tuts-plan.md: Marked Async Programming section as completed [x]
Batch 23 - Testing
Added comprehensive Vietnamese tutorials covering:
- Unit Testing: Testing individual functions and modules
* #[test] attribute for marking test functions
* Assert macros: assert!, assert_eq!, assert_ne!
* Running tests with cargo test and options
* Test organization in modules with #[cfg(test)]
* Testing functions, structs, and methods
* Error testing with #[should_panic] and Result
* #[ignore] for slow tests
* Testing private functions
* Real-world examples: calculator, string utils, vector operations,
user validation, shopping cart, bank account
- Integration Testing: Testing public API of crate
* Integration tests vs unit tests comparison
* tests/ directory structure
* Testing only public API
* Multiple test files organization
* Sharing test code with common/ module
* Testing binary crates by extracting to lib
* Best practices: test public API, one feature per file,
descriptive names, setup/teardown
* Real-world examples: string utils library, math library,
user management, calculator library, todo list
Both tutorials follow ELI5 approach with Vietnamese metaphors ("quality control",
"complete product testing"), extensive code examples (40+ examples),
practice exercises, and comprehensive comparison tables.
Updated:
- sidebars-rust.js: Added unit-testing and integration-testing to Advanced nav
- rust-tuts-plan.md: Marked Testing section as completed [x]
This completes ALL Advanced tutorials (32/32, 100% complete)! Added tutorial: - advanced/declarative-macros.md: Comprehensive guide to macro_rules! * macro_rules! basics and syntax * Pattern matching with designators (ident, expr, ty, etc.) * Multiple patterns and arguments * Repetition patterns: $(...)*, $(...)+ , $(…)? * Real-world examples: vec!, println!, test helpers * Advanced patterns: recursive macros, nested repetition * Internal rules (@internal pattern) * Common macro patterns: assert, unwrap_or_return, debug print * Macro hygiene and $crate usage * Practice exercises with solutions Updated files: - sidebars-rust.js: Added declarative-macros to Advanced section - rust-tuts-plan.md: Marked declarative-macros.md as completed [x] Tutorial covers: - Basic macro creation with macro_rules! - Pattern matching and designators - Repetition with comma-separated lists - Key-value pair patterns (hashmap example) - Struct and enum builders - Recursive macros (count example) - Matrix and nested repetition - Public vs internal rules - Macro hygiene for safe variable usage - 40+ comprehensive code examples - 3 practice exercises with solutions This tutorial teaches how to write declarative macros for code generation, reducing repetitive code and creating powerful compile-time abstractions. Milestone: Advanced section 100% complete (32/32 tutorials) Next sections: Projects, Practice, Reference, Glossary
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rust tuts - add first 61 posts