Skip to content

Reorganize command-based documentation for v2/v3 separation (Phase 1) #3165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
sciencewhiz merged 1 commit into from
Nov 19, 2025
Merged

Reorganize command-based documentation for v2/v3 separation (Phase 1) #3165

sciencewhiz merged 1 commit into from
Nov 19, 2025

Conversation

@jasondaming
Copy link
Member

@jasondaming jasondaming commented Nov 13, 2025

Summary

This PR reorganizes the existing command-based documentation into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project, addressing feedback from @SamCarlberg on PR #3095.

Changes

File Organization

  • Moved 12 v2 documentation files to commands-v2/ subdirectory (with git history preserved via git mv)
  • Created commands-v2/index.rst as the new landing page for Commands v2 documentation
  • Updated commandbased/index.rst to serve as a high-level framework chooser between v2 and v3

Cross-Reference Updates

  • Updated 4 internal references within v2 files to use the new commands-v2/ prefix
  • Updated 20 external files throughout the documentation to point to new v2 locations
  • Added 12 redirects in redirects.txt to ensure old URLs continue working

Files Moved

  • what-is-command-based.rst
  • commands.rst
  • command-compositions.rst
  • subsystems.rst
  • binding-commands-to-triggers.rst
  • structuring-command-based-project.rst
  • organizing-command-based.rst
  • command-scheduler.rst
  • cpp-command-discussion.rst
  • pid-subsystems-commands.rst
  • profile-subsystems-commands.rst
  • profilepid-subsystems-commands.rst

Rationale

This addresses the main concern from PR #3095 that the work was too large to review effectively. By splitting into phases:

  1. Phase 1 (this PR): Simple reorganization of existing v2 docs - easy to review
  2. Phase 2 (next PR): v3 documentation outline with TODO placeholders - review structure
  3. Phase 3 (subsequent PRs): Content filling with RLIs from verified examples - manageable chunks

Testing

  • All file moves preserve git history
  • All cross-references systematically updated
  • Redirects added for backward compatibility
  • No content changes to existing documentation

Checklist

  • File moves completed with git mv
  • New commands-v2/index.rst created
  • Main commandbased/index.rst updated
  • Internal cross-references updated
  • External cross-references updated (20 files)
  • Redirects added (12 entries)
  • CLAUDE.md excluded from commit

Related to #3095

🤖 Generated with Claude Code

@github-actions github-actions bot added the 2027 label Nov 13, 2025
@jasondaming jasondaming force-pushed the commands-v2-reorganization-2027 branch from b6306ed to b2f8678 Compare November 13, 2025 04:04
jasondaming added a commit to jasondaming/frc-docs that referenced this pull request Nov 13, 2025
@jasondaming
Add Commands v3 documentation outline (Phase 2)
e7021a1 
Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written.

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

Each file contains:
- Section headers outlining the article structure
- TODO directives describing what content should be written
- Guidance for future content writers on what to include

No actual tutorial content or code examples are included - this is purely structural planning for review.

Related to wpilibsuite#3095
Related to wpilibsuite#3165
@jasondaming jasondaming mentioned this pull request Nov 13, 2025
Open
10 tasks
@jasondaming jasondaming force-pushed the commands-v2-reorganization-2027 branch 2 times, most recently from cc4c49a to 8483432 Compare November 13, 2025 04:32
jasondaming added a commit to jasondaming/frc-docs that referenced this pull request Nov 13, 2025
@jasondaming
Add Commands v3 documentation outline (Phase 2)
d7fa6b9 
Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written.

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

Each file contains:
- Section headers outlining the article structure
- TODO directives describing what content should be written
- Guidance for future content writers on what to include

No actual tutorial content or code examples are included - this is purely structural planning for review.

Related to wpilibsuite#3095
Related to wpilibsuite#3165
@jasondaming
Reorganize command-based documentation for v2/v3 separation
4117fc9 
Move all Commands v2 documentation files into a commands-v2/ subdirectory to prepare for Commands v3 documentation. This is Phase 1 of the Commands v3 documentation project.

Changes:
- Move 12 v2 documentation files to commands-v2/ subdirectory (preserving git history)
- Create new commands-v2/index.rst as landing page for v2 docs
- Update main commandbased/index.rst to serve as high-level framework chooser
- Update 20 files with corrected cross-references to new v2 locations
- Add 12 redirects to ensure old URLs continue working

This reorganization addresses feedback on PR wpilibsuite#3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders.

Related to wpilibsuite#3095
@jasondaming jasondaming force-pushed the commands-v2-reorganization-2027 branch from 8483432 to 4117fc9 Compare November 13, 2025 04:39
jasondaming added a commit to jasondaming/frc-docs that referenced this pull request Nov 13, 2025
@jasondaming
Add Commands v3 documentation outline (Phase 2)
d7aa645 
Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written.

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

Each file contains:
- Section headers outlining the article structure
- TODO directives describing what content should be written
- Guidance for future content writers on what to include

No actual tutorial content or code examples are included - this is purely structural planning for review.

Related to wpilibsuite#3095
Related to wpilibsuite#3165
@sciencewhiz sciencewhiz merged commit e68f676 into wpilibsuite:2027 Nov 19, 2025
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sciencewhiz sciencewhiz sciencewhiz approved these changes

+1 more reviewer

@SamCarlberg SamCarlberg SamCarlberg approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

2027

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jasondaming @sciencewhiz @SamCarlberg