Add Commands v3 documentation outline (Phase 2)

[jasondaming]

Summary

This PR adds the structural outline for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This is Phase 2 of the Commands v3 documentation project, addressing feedback from @SamCarlberg on PR #3095.

This PR is for reviewing the documentation structure and organization only - no actual content is included yet.

Dependencies

This PR builds on PR #3165 (Phase 1: v2 reorganization). Review #3165 first.

Changes

Documentation Structure Created

Created 14 skeleton files in commands-v3/ directory:

1. index.rst - Landing page with overview, quick examples, and navigation
2. what-is-commands-v3.rst - Conceptual foundation and core concepts
3. getting-started.rst - Hands-on tutorial for first v3 program
4. mechanisms.rst - Deep dive into Mechanisms (v3's Subsystems)
5. commands-and-coroutines.rst - Core command creation and coroutine API
6. async-await-patterns.rst - Async/await helpers for orchestration
7. command-compositions.rst - Traditional composition groups
8. binding-commands-to-triggers.rst - Button bindings and triggers
9. priorities-and-interrupts.rst - Priority system and interruption
10. structuring-v3-project.rst - Code organization best practices
11. testing-and-simulation.rst - Testing commands with simulation
12. telemetry-and-debugging.rst - Enhanced telemetry and debugging
13. migration-from-v2.rst - Migration guide from v2 to v3
14. advanced-topics.rst - Advanced patterns and edge cases

What's Included in Each File

Each skeleton file contains:

• Title and purpose: Brief description of what the article covers
• Section headers: Organized outline of topics
• TODO directives: Detailed descriptions of what content should be written in each section
• Guidance for writers: Clear direction on examples, explanations, and code samples needed

What's NOT Included

• No actual tutorial content or detailed explanations
• No code examples or RLIs (those come in Phase 3)
• Just structural planning and content descriptions

Example: what-is-commands-v3.rst

Each file follows this pattern:

# What is Commands v3?

.. todo:: This article introduces the conceptual foundation...

## Introduction

.. todo::
   - Recap the command-based pattern
   - Explain what's fundamentally different in v3 vs v2
   - Why imperative style was chosen
   - Brief history: v1 → v2 → v3

## The Problem v3 Solves

.. todo::
   **Learning Curve Issues:**
   - v2 requires understanding functional composition...
   (detailed description of what to write)

Rationale

This phase allows review of:

• Documentation organization: Is the article structure logical?
• Topic coverage: Are all important v3 features covered?
• Article scope: Is each article focused on a clear topic?
• Content descriptions: Are TODO notes clear enough for future writers?

By reviewing structure first, we can adjust organization before investing time in writing full content.

Based On

This outline is based on:

• Commands v3 design document from @SamCarlberg
• allwpilib PR #6518 (v3 implementation)
• Analysis of what content teams will need to learn v3
• Feedback from PR Commands v3 Documentation #3095 to split work into phases

Next Steps (Phase 3)

After this structure is approved:

1. Create example projects in wpilibjExamples with verified code
2. Write content article-by-article with RLIs to examples
3. Submit content in small reviewable PRs (2-3 articles at a time)

Review Focus

Please review:

• Is the article organization logical?
• Are any important topics missing?
• Are any articles too broad or too narrow in scope?
• Are the TODO descriptions clear for future content writers?
• Does the structure match what teams need to learn v3?

Statistics

• 14 files created
• 1,213 lines added
• ~50 KB total
• Average 86 lines per file

Checklist

• 14 skeleton files created
• Each file has clear section structure
• TODO notes describe content needed
• No actual content written (structural only)
• Builds on Phase 1 (v2 reorganization) from PR Reorganize command-based documentation for v2/v3 separation (Phase 1) #3165

Related to #3095
Related to #3165

🤖 Generated with Claude Code

[SamCarlberg]

I think this page should focus on v3 standalone. Comparisons with v2 and v1 can live in the migration docs

[SamCarlberg]

Ditto

[SamCarlberg]

The more fundamental point with the learning curve is transitioning from a very basic "programmer's first program"-style project to something that can coordinate multi-mechanism actions and events. Simple imperative code can be dressed up, in a sense, by wrapping it in the command-related functions and changing some method calls to use coroutines (eg Thread.sleep or direct subroutine invocations). We don't need to go into details on this page, since it's a summary, but it's important to mention the on-ramp.

For example, a very simple drive-in-a-square routine:

void driveSquare() {
  for (int i = 0; i < 4; i++) {
    right.set(1);
    left.set(1);
    Thread.sleep(2500);

    right.set(1);
    left.set(-1);
    Thread.sleep(600);
  }
}

void driveManySquares(int count) {
  for (int i = 0; i < count; i++) {
    driveSquare();
  }
}

This can be lifted to a command almost entirely in place:

Command driveSquare() {
  return run(coroutine -> {
    for (int i = 0; i < 4; i++) {
      right.set(1);
      left.set(1);
      // Thread.sleep(2500);
      coroutine.wait(Milliseconds.of(2500));

      right.set(1);
      left.set(-1);
      // Thread.sleep(600);
      coroutine.wait(Milliseconds.of(600));
    }
  }).named("Drive Square");
}

Command driveManySquares(int count) {
  return run(coroutine -> {
    for (int i = 0; i < count; i++) {
      coroutine.await(driveSquare());
    }
  }).named("Drive " + count + " Squares");
}

[SamCarlberg]

Should inner implementation details like this be included? Doesn't seem like it'd be relevant to people being introduced to the library

[SamCarlberg]

There's not really a "generator" paradigm, since commands are void-returning.

[SamCarlberg]

v2 comparisons - probably best to leave in the migration guide

[SamCarlberg]

This seems very similar to the "Command Creation Patterns" above

[sciencewhiz]

Is coroutine knowledge necessary?

[jasondaming]

helpful but I don't think it is required. Maybe depends on at what level we call coroutine knowledge. @SamCarlberg ?

[sciencewhiz]

This template doesn't exist yet, right?

[jasondaming]

Yes but this is an outline

[sciencewhiz]

right, just figuring out what's needed that's outside of docs

[sciencewhiz]

This needs to be created, right?

[jasondaming]

Yes but this is an outline

[sciencewhiz]

This feels like a separate article

[jasondaming]

I think we should wait and see how big this section gets. If it starts to dominate the page absolutely but I am not sure it will at this point.

[sciencewhiz]

I'm thinking even if it doesn't dominate the page, it will be more easily found if it isn't hidden in getting started

[sciencewhiz]

This file shouldn't be commited

[sciencewhiz]

Maybe also cover an example of something that doesn't need to be encapsulated in a mechanism, like a vision system.

[sciencewhiz]

I'm thinking even if it doesn't dominate the page, it will be more easily found if it isn't hidden in getting started

[sciencewhiz]

Should have a what is a command, similar to what is a mechanism

[sciencewhiz]

Maybe something about the CommandHID classes vs regular HIS classes.

[sciencewhiz]

This feels like it might be better in the testing and simulation article, or at least the later topics in this section

[sciencewhiz]

Shouldn't this be how to install v3 vendordep?

[sciencewhiz]

This feels like it should be higher in the TOC before talking about the migration strategy

[sciencewhiz]

I'd move this into its own article and not hide in advanced topics