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

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 #3095 to split the work into manageable phases. The next phase will add v3 documentation structure with TODO placeholders.

Related to #3095

Author: jasondaming

source/docs/software/advanced-controls/controllers/pidcontroller.rst

@@ -2,7 +2,7 @@
 
 .. note:: This article focuses on in-code implementation of PID control in WPILib. For a conceptual explanation of the working of a PIDController, see :ref:`docs/software/advanced-controls/introduction/introduction-to-pid:Introduction to PID`
 
-.. note:: For a guide on implementing PID control through the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>`, see :ref:`docs/software/commandbased/pid-subsystems-commands:PID Control in Command-based`.
+.. note:: For a guide on implementing PID control through the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>`, see :ref:`docs/software/commandbased/commands-v2/pid-subsystems-commands:PID Control in Command-based`.
 
 WPILib supports PID control of mechanisms through the ``PIDController`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/math/controller/PIDController.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_p_i_d_controller.html), :external:py:class:`Python <wpimath.controller.PIDController>`).  This class handles the feedback loop calculation for the user, as well as offering methods for returning the error, setting tolerances, and checking if the control loop has reached its setpoint within the specified tolerances.
 

source/docs/software/advanced-controls/controllers/profiled-pidcontroller.rst

@@ -1,6 +1,6 @@
 # Combining Motion Profiling and PID Control with ProfiledPIDController
 
-.. note:: For a guide on implementing the ``ProfiledPIDController`` class in the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :ref:`docs/software/commandbased/profilepid-subsystems-commands:Combining Motion Profiling and PID in Command-Based`.
+.. note:: For a guide on implementing the ``ProfiledPIDController`` class in the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :ref:`docs/software/commandbased/commands-v2/profilepid-subsystems-commands:Combining Motion Profiling and PID in Command-Based`.
 
 In the previous article, we saw how to use the ``TrapezoidProfile`` class to create and use a trapezoidal motion profile.  The example code from that article demonstrates manually composing the ``TrapezoidProfile`` class with the external PID control feature of a "smart" motor controller.
 

source/docs/software/advanced-controls/controllers/trapezoidal-profiles.rst

@@ -4,7 +4,7 @@
 
 .. note:: This article covers the in-code generation of trapezoidal motion profiles.  Documentation describing the involved concepts in more detail is forthcoming.
 
-.. note:: For a guide on implementing the ``TrapezoidProfile`` class in the :ref:`command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :doc:`/docs/software/commandbased/profile-subsystems-commands`.
+.. note:: For a guide on implementing the ``TrapezoidProfile`` class in the :ref:`command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` framework, see :doc:`/docs/software/commandbased/commands-v2/profile-subsystems-commands`.
 
 .. note:: The ``TrapezoidProfile`` class, used on its own, is most useful when composed with a custom controller (such as a "smart" motor controller with a built-in PID functionality).  To integrate it with a WPILib ``PIDController``, see :doc:`profiled-pidcontroller`.
 

source/docs/software/basic-programming/functions-as-data.rst

@@ -10,7 +10,7 @@ Typically, code that calls a function is coupled to (depends on) the definition
 
 For example, WPILib offers several ways for users to execute certain code whenever a joystick button is pressed - one of the easiest and cleanest ways to do this is to allow the user to *pass a function* to one of the WPILib joystick methods.  This way, the user only has to write the code that deals with the interesting and team-specific things (e.g., "move my robot arm") and not the boring, error-prone, and universal thing ("properly read button inputs from a standard joystick").
 
-For another example, the :ref:`Command-based framework <docs/software/commandbased/what-is-command-based:What Is "Command-Based" Programming?>` is built on ``Command`` objects that refer to methods defined on various ``Subsystem`` classes.  Many of the included ``Command`` types (such as ``InstantCommand`` and ``RunCommand``) work with *any* function - not just functions associated with a single ``Subsystem``.  To support building commands generically, we need to support passing functions from a ``Subsystem`` (which interacts with the hardware) to a ``Command`` (which interacts with the scheduler).
+For another example, the :ref:`Command-based framework <docs/software/commandbased/commands-v2/what-is-command-based:What Is "Command-Based" Programming?>` is built on ``Command`` objects that refer to methods defined on various ``Subsystem`` classes.  Many of the included ``Command`` types (such as ``InstantCommand`` and ``RunCommand``) work with *any* function - not just functions associated with a single ``Subsystem``.  To support building commands generically, we need to support passing functions from a ``Subsystem`` (which interacts with the hardware) to a ``Command`` (which interacts with the scheduler).
 
 In these cases, we want to be able to pass a single function as a piece of data, as if it were a variable - it doesn't make sense to ask the user to provide an entire class, when we really just want them to give us a single appropriately-shaped function.
 
@@ -24,7 +24,7 @@ Java represents functions-as-data as instances of [functional interfaces](https:
 
 This might sound complicated, but in the context of WPILib we don't really need to worry much about using the functional interfaces themselves - the code that does that is internal to WPILib.  Instead, all we need to know is how to pass a function that we've written to a method that takes a functional interface as a parameter.  For a simple example, consider the signature of ``Commands.runOnce`` (which creates an ``InstantCommand`` that, when scheduled, runs the given function once and then terminates):
 
-.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands:getRequirements>`, and will not be discussed here.
+.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands-v2/commands:getRequirements>`, and will not be discussed here.
 ```java
 public static Command runOnce(Runnable action, Subsystem... requirements)
 ```
@@ -104,7 +104,7 @@ In WPILibC, function types are represented with the ``std::function`` class (htt
 
 This sounds a lot more complicated than it is to use in practice.  Let's look at the call signature of ``cmd::RunOnce`` (which creates an ``InstantCommand`` that, when scheduled, runs the given function once and then terminates):
 
-.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands:getRequirements>`, and will not be discussed here.
+.. note:: The ``requirements`` parameter is explained in the :ref:`Command-based documentation <docs/software/commandbased/commands-v2/commands:getRequirements>`, and will not be discussed here.
 
 ```c++
 CommandPtr RunOnce(

source/docs/software/basic-programming/joystick.rst

@@ -4,7 +4,7 @@
 
 A joystick can be used with the Driver Station program to control the robot.  Almost any "controller" that can be recognized by Windows can be used as a joystick.  Joysticks are accessed using the ``GenericHID`` class.  This class has three relevant subclasses for preconfigured joysticks.  You may also implement your own for other controllers by extending ``GenericHID``.  The first is ``Joystick`` which is useful for standard flight joysticks.  The second is ``XboxController`` which works for the Xbox 360, Xbox One, or Logitech F310 (in XInput mode).  Finally, the ``PS4Controller`` class is ideal for using that controller.  Each axis of the controller ranges from -1 to 1.
 
-The command based way to use the these classes is detailed in the section: :ref:`docs/software/commandbased/binding-commands-to-triggers:Binding Commands to Triggers`.
+The command based way to use the these classes is detailed in the section: :ref:`docs/software/commandbased/commands-v2/binding-commands-to-triggers:Binding Commands to Triggers`.
 
 ## Driver Station Joysticks
 
@@ -136,7 +136,7 @@ An axis can be used with ``.getRawAxis(int index)`` (if not using any of the cla
 
 ## Button Usage
 
-.. note:: Usage such as the following is for code not using the command-based framework. For button usage in the command-based framework, see :ref:`docs/software/commandbased/binding-commands-to-triggers:Binding Commands to Triggers`.
+.. note:: Usage such as the following is for code not using the command-based framework. For button usage in the command-based framework, see :ref:`docs/software/commandbased/commands-v2/binding-commands-to-triggers:Binding Commands to Triggers`.
 
 Unlike an axis, you will usually want to use the ``pressed`` and ``released`` methods to respond to button input.  These will return true if the button has been activated since the last check.  This is helpful for taking an action once when the event occurs but not having to continuously do it while the button is held down.
 

…ndbased/binding-commands-to-triggers.rst …ands-v2/binding-commands-to-triggers.rstsource/docs/software/commandbased/binding-commands-to-triggers.rst renamed to source/docs/software/commandbased/commands-v2/binding-commands-to-triggers.rst source/docs/software/commandbased/binding-commands-to-triggers.rst renamed to source/docs/software/commandbased/commands-v2/binding-commands-to-triggers.rst

@@ -327,4 +327,4 @@ Command compositions can also be written as a constructor-only subclass of the m
          :lines: 7-
          :lineno-match:
 
-The advantages and disadvantages of this subclassing approach in comparison to others are discussed in :ref:`docs/software/commandbased/organizing-command-based:Subclassing Command Groups`.
+The advantages and disadvantages of this subclassing approach in comparison to others are discussed in :ref:`docs/software/commandbased/commands-v2/organizing-command-based:Subclassing Command Groups`.

…re/commandbased/command-compositions.rst …sed/commands-v2/command-compositions.rstsource/docs/software/commandbased/command-compositions.rst renamed to source/docs/software/commandbased/commands-v2/command-compositions.rst source/docs/software/commandbased/command-compositions.rst renamed to source/docs/software/commandbased/commands-v2/command-compositions.rst

@@ -19,7 +19,7 @@ To schedule a command, users call the ``schedule()`` method ([Java](https://gith
 This method walks through the following steps:
 
 #. Verifies that the command isn't in a composition.
-#. :term:`No-op` if scheduler is disabled, command is already scheduled, or robot is disabled and command doesn't :ref:`docs/software/commandbased/commands:runsWhenDisabled`.
+#. :term:`No-op` if scheduler is disabled, command is already scheduled, or robot is disabled and command doesn't :ref:`docs/software/commandbased/commands-v2/commands:runsWhenDisabled`.
 #. If requirements are in use:
 
    * If all conflicting commands are interruptible, cancel them.

…tware/commandbased/command-scheduler.rst …dbased/commands-v2/command-scheduler.rstsource/docs/software/commandbased/command-scheduler.rst renamed to source/docs/software/commandbased/commands-v2/command-scheduler.rst source/docs/software/commandbased/command-scheduler.rst renamed to source/docs/software/commandbased/commands-v2/command-scheduler.rst

@@ -98,7 +98,7 @@ As a rule, command compositions are ``kCancelIncoming`` if all their components
 
 ## Included Command Types
 
-The command-based library includes many pre-written command types. Through the use of :ref:`lambdas <docs/software/commandbased/index:Lambda Expressions (Java)>`, these commands can cover almost all use cases and teams should rarely need to write custom command classes. Many of these commands are provided via static factory functions in the ``Commands`` utility class (Java), in the ``frc2::cmd`` namespace defined in the ``Commands.h`` header (C++), or in the ``commands2.cmd`` namespace (Python). In Java and C++, classes inheriting from ``Subsystem`` also have instance methods that implicitly require ``this``.
+The command-based library includes many pre-written command types. Through the use of :ref:`lambdas <docs/software/commandbased/commands-v2/index:Lambda Expressions (Java)>`, these commands can cover almost all use cases and teams should rarely need to write custom command classes. Many of these commands are provided via static factory functions in the ``Commands`` utility class (Java), in the ``frc2::cmd`` namespace defined in the ``Commands.h`` header (C++), or in the ``commands2.cmd`` namespace (Python). In Java and C++, classes inheriting from ``Subsystem`` also have instance methods that implicitly require ``this``.
 
 ### Running Actions
 
@@ -306,7 +306,7 @@ To wait until a certain condition becomes ``true``, the library offers the ``Com
 
 There are commands for various control setups:
 
-- ``TrapezoidProfile`` tracks a trapezoid motion profile. For more info, see :doc:`/docs/software/commandbased/profile-subsystems-commands`.
+- ``TrapezoidProfile`` tracks a trapezoid motion profile. For more info, see :doc:`/docs/software/commandbased/commands-v2/profile-subsystems-commands`.
 
 - ``MecanumControllerCommand`` ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/MecanumControllerCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_mecanum_controller_command.html)) is useful for controlling mecanum drivetrains. See API docs and the **MecanumControllerCommand** ([Java](https://github.com/wpilibsuite/allwpilib/tree/2027/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/mecanumcontrollercommand), [C++](https://github.com/wpilibsuite/allwpilib/tree/2027/wpilibcExamples/src/main/cpp/examples/MecanumControllerCommand)) example project for more info.
 

…/docs/software/commandbased/commands.rst …re/commandbased/commands-v2/commands.rstsource/docs/software/commandbased/commands.rst renamed to source/docs/software/commandbased/commands-v2/commands.rst source/docs/software/commandbased/commands.rst renamed to source/docs/software/commandbased/commands-v2/commands.rst

@@ -3,7 +3,7 @@
 
 This article will help you understand the reasoning behind some of the decisions made in the 2020 command-based framework (such as the use of ``std::unique_ptr``, CRTP in the form of ``CommandHelper<Base, Derived>``, etc.).  You do not need to understand the information within this article to use the command-based framework in your robot code.
 
-.. note:: The model was further changed in 2023, as described :ref:`below <docs/software/commandbased/cpp-command-discussion:2023 Updates>`.
+.. note:: The model was further changed in 2023, as described :ref:`below <docs/software/commandbased/commands-v2/cpp-command-discussion:2023 Updates>`.
 
 ## Ownership Model
 The old command-based framework employed the use of raw pointers, meaning that users had to use ``new`` (resulting in manual heap allocations) in their robot code. Since there was no clear indication on who owned the commands (the scheduler, the command groups, or the user themselves), it was not apparent who was supposed to take care of freeing the memory.
@@ -167,7 +167,7 @@ After a few years in the new command-based framework, the recommended way to cre
 
 A significant root cause of most pain points was commands being passed by value in a non-polymorphic way. This made object slicing mistakes rather easy, and changes in composition structure could propagate type changes throughout the codebase: for example, if a ``ParallelRaceGroup`` were changed to a ``ParallelDeadlineGroup``, those type changes would propagate through the codebase. Passing around the object as a ``Command`` (as done in Java) would result in object slicing.
 
-Additionally, various decorators weren't supported in C++ due to reasons described :ref:`above <docs/software/commandbased/cpp-command-discussion:Templating Decorators>`. As long as decorators were rarely used and were mainly to reduce verbosity (where Java was more verbose than C++), this was less of a problem. Once heavy usage of decorators was recommended, this became more of an issue.
+Additionally, various decorators weren't supported in C++ due to reasons described :ref:`above <docs/software/commandbased/commands-v2/cpp-command-discussion:Templating Decorators>`. As long as decorators were rarely used and were mainly to reduce verbosity (where Java was more verbose than C++), this was less of a problem. Once heavy usage of decorators was recommended, this became more of an issue.
 
 ### ``CommandPtr``