Add Commands v3 documentation outline (Phase 2)

source/docs/software/commandbased/commands-v3/advanced-topics.rst

@@ -0,0 +1,55 @@
+# Advanced Topics
+
+.. todo::
+   This article covers advanced patterns, optimizations, and edge cases in Commands v3. This content is for experienced teams who have mastered the basics and want to push v3 to its limits or handle unusual requirements.
+
+## Custom Command Base Classes
+
+.. todo::
+   Explain how and when to create custom base classes for commands. Cover:
+   - When custom base classes are useful vs. unnecessary abstraction
+   - Creating abstract command base classes with common functionality
+   - Decorator pattern for command functionality
+   - Wrapping commands to add cross-cutting concerns
+   - Best practices for base class design
+   - Examples of useful base class patterns (describe scenarios, not full implementations)
+
+## Performance Optimization
+
+.. todo::
+   Provide guidance on optimizing v3 command performance. Cover:
+   - Understanding scheduler overhead
+   - Minimizing allocations in command execution
+   - Efficient trigger condition evaluation
+   - Optimizing periodic operations
+   - Profiling v3 command code
+   - Trade-offs between readability and performance
+   - When optimization matters vs. premature optimization
+   - Benchmarking techniques
+
+## Advanced Async Patterns
+
+.. todo::
+   Showcase advanced patterns using async/await and coroutines. Cover:
+   - Command pipelines and streaming patterns
+   - State machines implemented with async/await
+   - Error handling and recovery with async commands
+   - Cancellation and timeout patterns
+   - Coordinating multiple mechanisms with complex dependencies
+   - Real-time responsive commands with background processing
+   - Describe complex scenarios and how to implement them with v3 features
+
+## Edge Cases and Gotchas
+
+.. todo::
+   Document edge cases, limitations, and common pitfalls. Cover:
+   - Commands that never yield (infinite loops without yield)
+   - Forked commands and lifecycle management
+   - Nested trigger scopes and cleanup
+   - Priority conflicts
+   - Requirements conflicts with complex command compositions
+   - Thread safety considerations (if any)
+   - Limitations of the coroutine model
+   - Breaking scheduler assumptions
+   - Common mistakes and how to avoid them
+   - What NOT to do in v3 commands

source/docs/software/commandbased/commands-v3/async-await-patterns.rst

@@ -0,0 +1,78 @@
+# Async/Await Patterns
+
+.. todo::
+   This article explains the async/await helper functions that enable advanced command orchestration in v3. These functions allow commands to launch other commands and wait for them to complete, enabling powerful composition patterns. Teams should understand basic command creation before reading this article.
+
+## Introduction to Async/Await
+
+.. todo::
+   Provide an overview of async/await in Commands v3. Cover:
+   - What async/await means in the context of v3 (not OS-level async)
+   - Why async/await is useful for command orchestration
+   - How async/await differs from composition groups
+   - When to use async/await vs. other patterns
+   - High-level mental model for how it works with the scheduler
+   - Relationship to coroutines and yield()
+
+## fork()
+
+.. todo::
+   Explain the fork() function in detail. Cover:
+   - What fork(command) does: launch a command without waiting for it
+   - "Fire and forget" semantics
+   - Lifecycle of forked commands relative to parent
+   - Requirements and priority considerations
+   - Common use cases (background operations, side effects, etc.)
+   - Potential pitfalls and how to avoid them
+   - Examples of fork() patterns (describe what examples should show)
+
+## await()
+
+.. todo::
+   Explain the await() function in detail. Cover:
+   - What await(command) does: schedule a command and wait for it to complete
+   - Easier to explain as a blocking version of fork()
+   - How await() blocks the calling command until the child completes
+   - Requirements and priority handling with awaited commands
+   - What happens if the awaited command is interrupted
+   - What happens if the parent command is interrupted
+   - Return values and status from awaited commands
+   - When to use fork() vs. await()
+   - Examples of await() patterns (describe what examples should show)
+
+## awaitAll()
+
+.. todo::
+   Explain the awaitAll() function in detail. Cover:
+   - What awaitAll(commands) does: wait for multiple commands in parallel
+   - How awaitAll() differs from await() in a loop
+   - When all commands must complete vs. early termination scenarios
+   - Requirements management across multiple parallel commands
+   - Error and interruption handling
+   - Performance implications of parallel execution
+   - Examples of awaitAll() patterns (describe what examples should show)
+
+## awaitAny()
+
+.. todo::
+   Explain the awaitAny() function in detail. Cover:
+   - What awaitAny(commands) does: wait until any command completes
+   - Race condition semantics: which command "wins"
+   - **Important**: awaitAny() cancels all other still-running commands when one completes
+   - Both await functions are blocking
+   - Use cases for awaitAny() (timeouts, alternative paths, etc.)
+   - How interruption is handled
+   - Differences from race groups in composition
+   - Examples of awaitAny() patterns (describe what examples should show)
+
+## Practical Patterns
+
+.. todo::
+   Showcase common practical patterns combining async/await functions. Cover:
+   - Timeout patterns: use awaitAny() with a timeout command alongside the main command - first to complete wins
+   - Sequential operations with conditional logic
+   - Parallel operations with synchronization points
+   - Launching background tasks with fork()
+   - Complex state machines using async/await
+   - Error recovery and fallback patterns
+   - Describe several real-world scenarios and which async/await functions to combine

source/docs/software/commandbased/commands-v3/binding-commands-to-triggers.rst

@@ -0,0 +1,80 @@
+# Binding Commands to Triggers
+
+.. todo::
+   This article explains how to connect commands to button inputs and other events using the trigger system. Triggers are how robot code responds to driver input and sensor events. This is essential knowledge for any team using Commands v3.
+
+## Triggers Overview
+
+.. todo::
+   Provide an overview of the trigger system in v3. Cover:
+   - What triggers are and their role in the command framework
+   - How triggers differ from directly calling command.schedule()
+   - When trigger bindings are evaluated by the scheduler
+   - Available trigger sources (buttons, joysticks, sensors, custom)
+   - High-level syntax for creating and binding triggers
+
+## Button Bindings
+
+.. todo::
+   Explain how to bind commands to physical buttons. Cover:
+   - CommandHID classes vs. regular HID classes (CommandXboxController vs. XboxController, etc.)
+   - When to use each type of controller class
+   - Accessing button triggers from controllers/joysticks
+   - Available binding methods: onTrue(), onFalse(), whileTrue(), whileFalse(), toggleOnTrue(), etc.
+   - When each binding type activates and deactivates commands
+   - Multiple bindings on the same button
+   - Button composition (modifier keys, button combinations)
+   - Best practices for organizing button bindings in RobotContainer
+   - Examples of common button binding patterns (describe what examples should show)
+
+## Creating Custom Triggers
+
+.. todo::
+   Explain how to create custom triggers beyond simple buttons. Cover:
+   - Creating triggers from boolean supplier functions
+   - Sensor-based triggers (limit switches, photoelectric sensors, etc.)
+   - State-based triggers (robot state, game piece detection, etc.)
+   - Time-based triggers
+   - Network table triggers
+   - Performance considerations for trigger condition functions
+   - Best practices for custom trigger implementation
+   - Examples of custom trigger patterns (describe what examples should show)
+
+## Trigger Composition
+
+.. todo::
+   Explain how to compose triggers using logical operations. Cover:
+   - Available composition operations: and(), or(), negate()
+   - Creating complex trigger conditions from simple ones
+   - Debouncing triggers
+   - Edge detection (rising/falling edges)
+   - Trigger filtering and transformation
+   - When composition is evaluated
+   - Note: This section may need updates if https://github.com/wpilibsuite/allwpilib/pull/8366 is merged
+   - Examples of trigger composition patterns (describe what examples should show)
+
+## Inner Trigger Scopes
+
+.. todo::
+   Explain inner trigger scopes for command-local bindings. Cover:
+   - What inner trigger scopes are and when to use them
+   - How to create an inner scope within a command
+   - Lifecycle of inner scope bindings (when they're active)
+   - Use cases: responding to events during command execution
+   - How inner scopes interact with command interruption
+   - Cleanup of inner scope bindings
+   - Differences from global trigger bindings
+   - Examples of inner scope patterns (describe what examples should show)
+
+## Practical Patterns
+
+.. todo::
+   Showcase common practical patterns for trigger usage. Cover:
+   - Organizing bindings in RobotContainer
+   - Driver control schemes (tank drive, arcade drive, split stick, etc.)
+   - Operator control panels and button boxes
+   - Mode switching and control profiles
+   - Cancellation buttons and emergency stops
+   - Trigger-based autonomous selection
+   - Testing and debugging trigger bindings
+   - Describe several real-world scenarios and recommended trigger patterns

source/docs/software/commandbased/commands-v3/command-compositions.rst

@@ -0,0 +1,89 @@
+# Command Compositions
+
+.. todo::
+   This article covers the traditional command composition groups that allow combining multiple commands into more complex behaviors. While v3 emphasizes async/await patterns, composition groups are still important and useful in many scenarios. This article should help teams understand when to use compositions vs. async/await.
+
+## Composition Overview
+
+.. todo::
+   Provide an overview of command composition in v3. Cover:
+   - What command compositions are and why they exist
+   - How compositions differ from async/await patterns
+   - When to use compositions vs. async/await
+   - Available composition types in v3
+   - General syntax and usage patterns
+
+## Sequence Groups
+
+.. todo::
+   Explain sequence command groups in detail. Cover:
+   - What sequence groups do: run commands one after another
+   - How to create a sequence group
+   - When commands transition in the sequence
+   - What happens if a command in the sequence is interrupted
+   - Requirements aggregation across sequence members
+   - Common use cases for sequences
+   - Comparison to using await() in a coroutine
+   - Examples of sequence group patterns (describe what examples should show)
+
+## Parallel Groups
+
+.. todo::
+   Explain parallel command groups in detail. Cover:
+   - What parallel groups do: run multiple commands simultaneously
+   - How to create a parallel group
+   - Note: All composition groups (parallel, race, deadline) are implemented as parallel groups with different configurations: Parallel groups have _n_ required commands and _m_ optional commands. The group exits once all _n_ required commands have exited. "Traditional" parallel groups: _m_ = 0 (every command is required). Race groups: _n_ = 0 (every command is optional, exits when any finishes). Deadline groups: both _n_ and _m_ are nonzero (mix of required and optional). Note: v2 deadlines were special case where _n_ = 1 and _m_ ≥ 1; v3 deadlines are generalized.
+   - Requirements handling with overlapping requirements
+   - What happens if one command is interrupted
+   - Common use cases for parallel groups
+   - Comparison to using awaitAll() in a coroutine
+   - Examples of parallel group patterns (describe what examples should show)
+
+## Race Groups
+
+.. todo::
+   Explain race command groups in detail. Cover:
+   - What race groups do: run commands in parallel until one finishes
+   - How to create a race group
+   - When the race group completes (first command finishes)
+   - What happens to other commands when one finishes
+   - Common use cases for race groups (timeouts, alternatives)
+   - Comparison to using awaitAny() in a coroutine
+   - Examples of race group patterns (describe what examples should show)
+
+## Deadline Groups
+
+.. todo::
+   Explain deadline command groups in detail. Cover:
+   - What deadline groups do: run commands with one as a "deadline"
+   - How to create a deadline group and specify the deadline command
+   - When the deadline group completes
+   - Differences between deadline command and other commands
+   - Common use cases for deadline groups
+   - How to achieve similar behavior with async/await
+   - Examples of deadline group patterns (describe what examples should show)
+
+## Repeating and Looping
+
+.. todo::
+   Explain repeating and looping command patterns. Cover:
+   - Available repeat/loop composition functions
+   - Infinite repeats vs. counted repeats
+   - When the loop terminates
+   - How interruption affects repeated commands
+   - Performance implications of repeated compositions
+   - Common use cases for repeating commands
+   - Comparison to using yield() loops in coroutines
+   - Examples of repeat patterns (describe what examples should show)
+
+## Conditional Groups
+
+.. todo::
+   Explain conditional command execution patterns. Cover:
+   - Available conditional composition functions (if/else-style branching)
+   - How conditions are evaluated
+   - When condition evaluation happens (command creation vs. execution)
+   - Proxy commands and deferred command selection
+   - Common use cases for conditional groups
+   - Comparison to using if/else in coroutines
+   - Examples of conditional patterns (describe what examples should show)

source/docs/software/commandbased/commands-v3/commands-and-coroutines.rst

@@ -0,0 +1,83 @@
+# Commands and Coroutines
+
+.. todo::
+   This article covers the core of Commands v3: creating commands using the coroutine API. It explains the fundamental building blocks of command creation, the coroutine control flow primitives, and how command lifecycle works. This should be one of the first articles teams read when learning v3.
+
+## Command Creation Patterns
+
+.. todo::
+   Describe the different ways to create commands in v3. Cover:
+   - Basic command creation using coroutine functions
+   - Inline vs. named command functions
+   - Commands as methods on Mechanism classes (factories)
+   - Commands as standalone functions in command files
+   - Lambda/anonymous command functions
+   - When to use each pattern
+   - Code examples showing syntax for each approach (structure only, not full implementations)
+
+## The Coroutine API
+
+.. todo::
+   Provide an overview of what coroutines are and how v3 uses them. Cover:
+   - High-level explanation of coroutines for teams unfamiliar with the concept
+   - How coroutines enable sequential command logic without state machines
+   - The yield paradigm
+   - How the scheduler executes coroutine commands
+   - Benefits of the coroutine approach
+
+## yield()
+
+.. todo::
+   Explain the yield() primitive in detail. Cover:
+   - What yield() does: pause execution and resume next cycle
+   - When to use yield() vs. other control flow primitives
+   - How yield() relates to the scheduler loop timing
+   - Common patterns using yield() (e.g., running for multiple cycles)
+   - Note: The compiler plugin checks for `yield` in while-loops (this check does not apply to other loop types)
+   - Performance implications
+   - Examples of yield() usage patterns (describe what examples should show)
+
+## park()
+
+.. todo::
+   Explain the park() primitive in detail. Cover:
+   - What park() does: pause indefinitely until command is interrupted
+   - When to use park() (e.g., commands that should run until interrupted)
+   - How park() differs from yield() in a loop
+   - Note: The compiler plugin checks for unreachable code after a `park()` call
+   - Interaction with command interruption and priorities
+   - Common use cases for park()
+   - Examples of park() usage patterns (describe what examples should show)
+
+## wait()/waitUntil()
+
+.. todo::
+   Explain the wait() and waitUntil() primitives. Cover:
+   - wait(duration): pause for a specific time period
+   - waitUntil(condition): pause until a condition becomes true
+   - How these differ from yield() loops
+   - Timeout behavior and edge cases
+   - Best practices for conditions in waitUntil()
+   - Performance and timing accuracy considerations
+   - Examples of wait/waitUntil patterns (describe what examples should show)
+
+## Command Lifecycle
+
+.. todo::
+   Describe the lifecycle of a command from creation to completion. Cover:
+   - When a command is created vs. when it starts executing
+   - The execution cycle: initialization, periodic execution, ending
+   - How coroutines map to the lifecycle phases
+   - What happens when a command completes normally
+   - What happens when a command is interrupted
+   - Cleanup and resource management
+
+## Command Properties
+
+.. todo::
+   Explain the various properties that can be set on commands. Cover:
+   - Available properties: name, priority, interruptible, runsWhenDisabled, etc.
+   - How to set command properties (method chaining, decorators, etc.)
+   - When properties are evaluated vs. applied
+   - How properties affect scheduler behavior
+   - Best practices for setting properties