From a38e87434a85dc19270067829386253fcb356fda Mon Sep 17 00:00:00 2001 From: jasondaming Date: Thu, 9 Oct 2025 07:01:01 -0500 Subject: [PATCH 1/4] Update robotpy_extras to components in documentation Fixes #3119 --- .../docs/software/python/pyproject_toml.rst | 4 +- .../roborio/using-multiple-cameras.rst | 8 +-- .../using-the-cameraserver-on-the-roborio.rst | 6 +- .../vscode-overview/3rd-party-libraries.rst | 70 +++++++++---------- 4 files changed, 44 insertions(+), 44 deletions(-) diff --git a/source/docs/software/python/pyproject_toml.rst b/source/docs/software/python/pyproject_toml.rst index 4fb249883f..255d910623 100644 --- a/source/docs/software/python/pyproject_toml.rst +++ b/source/docs/software/python/pyproject_toml.rst @@ -18,7 +18,7 @@ The ``pyproject.toml`` file looks something like this: robotpy_version = "2024.2.1.0" # Which extra RobotPy components should be installed # -> equivalent to `pip install robotpy[extra1, ...] -robotpy_extras = [ +components = [ # "all" # "apriltag" # "commands2" @@ -40,7 +40,7 @@ Each of the following will instruct the deploy process to install packages to th ``robotpy_version`` is the version of the ``robotpy`` PyPI package that this robot code depends on. -``robotpy_extras`` defines extra RobotPy components that can be installed, as only the core RobotPy libraries are installed by default. +``components`` defines extra RobotPy components that can be installed, as only the core RobotPy libraries are installed by default. ``requires`` is a list of strings, and each item is equivalent to a line of a [requirements.txt](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file. You can install any pure python packages on the roboRIO and they will likely work, but any packages that have binary dependencies must be cross-compiled for the roboRIO. For example, if you needed to use ``numpy`` in your robot code: diff --git a/source/docs/software/vision-processing/roborio/using-multiple-cameras.rst b/source/docs/software/vision-processing/roborio/using-multiple-cameras.rst index 05dc64ad9a..cd2603538d 100644 --- a/source/docs/software/vision-processing/roborio/using-multiple-cameras.rst +++ b/source/docs/software/vision-processing/roborio/using-multiple-cameras.rst @@ -96,8 +96,8 @@ If you're interested in just switching what the driver sees, and are using Smart ```toml [tool.robotpy] ... - # Add cscore to the robotpy-extras list - robotpy_extras = ["cscore"] + # Add cscore to the components list + components = ["cscore"] ``` If you're using some other dashboard, you can change the camera used by the camera server dynamically. If you open a stream viewer nominally to camera1, the robot code will change the stream contents to either camera1 or camera2 based on the joystick trigger. @@ -259,8 +259,8 @@ By default, the cscore library is pretty aggressive in turning off cameras not i ```toml [tool.robotpy] ... - # Add cscore to the robotpy-extras list - robotpy_extras = ["cscore"] + # Add cscore to the components list + components = ["cscore"] ``` .. note:: diff --git a/source/docs/software/vision-processing/roborio/using-the-cameraserver-on-the-roborio.rst b/source/docs/software/vision-processing/roborio/using-the-cameraserver-on-the-roborio.rst index 4fa284ca16..a69d5e47b3 100644 --- a/source/docs/software/vision-processing/roborio/using-the-cameraserver-on-the-roborio.rst +++ b/source/docs/software/vision-processing/roborio/using-the-cameraserver-on-the-roborio.rst @@ -81,13 +81,13 @@ In the following example a thread created in ``Robot`` constructor gets the Came :lines: 12-55 :linenos: - You need to update ``pyproject.toml`` contents to include cscore in the robotpy-extras key (this only shows the portions you need to update): + You need to update ``pyproject.toml`` contents to include cscore in the components key (this only shows the portions you need to update): ```toml [tool.robotpy] ... - # Add cscore to the robotpy-extras list - robotpy_extras = ["cscore"] + # Add cscore to the components list + components = ["cscore"] ``` Notice that in these examples, the ``PutVideo()`` method writes the video to a named stream. To view that stream on SmartDashboard or Shuffleboard, select that named stream. In this case that is "Rectangle". diff --git a/source/docs/software/vscode-overview/3rd-party-libraries.rst b/source/docs/software/vscode-overview/3rd-party-libraries.rst index 33a2ec50a7..e91279f359 100644 --- a/source/docs/software/vscode-overview/3rd-party-libraries.rst +++ b/source/docs/software/vscode-overview/3rd-party-libraries.rst @@ -44,50 +44,50 @@ Vendor dependencies are installed on a per-project basis (so each robot project All RobotPy project dependencies are specified in ``pyproject.toml``. You can add additional vendor-specific dependencies either by: - * Adding the component name to ``robotpy_extras`` + * Adding the component name to ``components`` * Adding the PyPI package name to ``requires`` .. seealso:: :doc:`/docs/software/python/pyproject_toml` Optional WPILib components: - +----------+----------------+---------------------+ - | | robotpy_extras | requires | - +==========+================+=====================+ - | Apriltag | apriltag | robotpy-apriltag | - +----------+----------------+---------------------+ - | Commands | commands2 | robotpy-commands-v2 | - +----------+----------------+---------------------+ - | cscore | cscore | robotpy-cscore | - +----------+----------------+---------------------+ - | Romi | romi | robotpy-romi | - +----------+----------------+---------------------+ - | XRP | xrp | robotpy-xrp | - +----------+----------------+---------------------+ + +----------+------------+---------------------+ + | | components | requires | + +==========+============+=====================+ + | Apriltag | apriltag | robotpy-apriltag | + +----------+------------+---------------------+ + | Commands | commands2 | robotpy-commands-v2 | + +----------+------------+---------------------+ + | cscore | cscore | robotpy-cscore | + +----------+------------+---------------------+ + | Romi | romi | robotpy-romi | + +----------+------------+---------------------+ + | XRP | xrp | robotpy-xrp | + +----------+------------+---------------------+ Optional vendor-specific components (not all are available at the beginning of the season): - +---------------------+-----------+-------------------+---------------------------+ - | | Origin | robotpy_extras | requires | - +=====================+===========+===================+===========================+ - | ChoreoLib | Vendor | | sleipnirgroup-choreolib | - +---------------------+-----------+-------------------+---------------------------+ - | CTRE Phoenix 6 | Vendor | phoenix6 | phoenix6 | - +---------------------+-----------+-------------------+---------------------------+ - | CTRE Phoenix 5 | Community | phoenix5 | robotpy-ctre | - +---------------------+-----------+-------------------+---------------------------+ - | PathPlannerLib | Vendor | pathplannerlib | robotpy-pathplannerlib | - +---------------------+-----------+-------------------+---------------------------+ - | PhotonVision | Vendor | photonvision | photonlibpy | - +---------------------+-----------+-------------------+---------------------------+ + +---------------------+-----------+-------------+---------------------------+ + | | Origin | components | requires | + +=====================+===========+=============+===========================+ + | ChoreoLib | Vendor | | sleipnirgroup-choreolib | + +---------------------+-----------+-------------+---------------------------+ + | CTRE Phoenix 6 | Vendor | phoenix6 | phoenix6 | + +---------------------+-----------+-------------+---------------------------+ + | CTRE Phoenix 5 | Community | phoenix5 | robotpy-ctre | + +---------------------+-----------+-------------+---------------------------+ + | PathPlannerLib | Vendor | pathplannerlib | robotpy-pathplannerlib | + +---------------------+-----------+-------------+---------------------------+ + | PhotonVision | Vendor | photonvision | photonlibpy | + +---------------------+-----------+-------------+---------------------------+ | Playing With Fusion | Community | playingwithfusion | robotpy-playingwithfusion | - +---------------------+-----------+-------------------+---------------------------+ - | REVLib | Community | rev | robotpy-rev | - +---------------------+-----------+-------------------+---------------------------+ - | Studica | Community | navx | robotpy-navx | - +---------------------+-----------+-------------------+---------------------------+ - | URCL | Community | | robotpy-urcl | - +---------------------+-----------+-------------------+---------------------------+ + +---------------------+-----------+-------------+---------------------------+ + | REVLib | Community | rev | robotpy-rev | + +---------------------+-----------+-------------+---------------------------+ + | Studica | Community | navx | robotpy-navx | + +---------------------+-----------+-------------+---------------------------+ + | URCL | Community | | robotpy-urcl | + +---------------------+-----------+-------------+---------------------------+ When using ``requires``, you can specify a version by appending ``==`` to the package name, e.g. ``robotpy-commands-v2==2024.0.0``. If you do not specify a version, the latest version will be installed. @@ -155,4 +155,4 @@ Vendor dependencies are installed on a per-project basis (so each robot project .. tab-item:: Python :sync: python - Third party libraries are packaged into Python wheels and uploaded to PyPI (if pure python) and/or WPILib's artifactory. Users can enable them as dependencies either by adding the component name to ``robotpy_extras`` (recommended) or by adding an explicit dependency for the PyPI package in ``requires``. The dependencies are downloaded when ``robotpy sync`` is executed, and installed on the roboRIO when ``robotpy deploy`` is executed. + Third party libraries are packaged into Python wheels and uploaded to PyPI (if pure python) and/or WPILib's artifactory. Users can enable them as dependencies either by adding the component name to ``components`` (recommended) or by adding an explicit dependency for the PyPI package in ``requires``. The dependencies are downloaded when ``robotpy sync`` is executed, and installed on the roboRIO when ``robotpy deploy`` is executed. From a68e83a4f5702235c9ee2240f2a46f27ab7f9c50 Mon Sep 17 00:00:00 2001 From: jasondaming Date: Thu, 9 Oct 2025 21:22:06 -0500 Subject: [PATCH 2/4] Address review feedback: clarify components vs requires usage - components is only for core WPILib packages - Vendor packages must use requires - Removed components column from vendor packages table - Updated documentation text to clarify the distinction --- CLAUDE.md | 1 + .../docs/software/python/pyproject_toml.rst | 2 +- .../vscode-overview/3rd-party-libraries.rst | 54 +++++++++---------- 3 files changed, 29 insertions(+), 28 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..1ffa90af53 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +- never work on an issue that already has a PR fixing it \ No newline at end of file diff --git a/source/docs/software/python/pyproject_toml.rst b/source/docs/software/python/pyproject_toml.rst index 255d910623..cfb244570f 100644 --- a/source/docs/software/python/pyproject_toml.rst +++ b/source/docs/software/python/pyproject_toml.rst @@ -40,7 +40,7 @@ Each of the following will instruct the deploy process to install packages to th ``robotpy_version`` is the version of the ``robotpy`` PyPI package that this robot code depends on. -``components`` defines extra RobotPy components that can be installed, as only the core RobotPy libraries are installed by default. +``components`` defines which optional core WPILib packages should be installed (equivalent to ``pip install robotpy[component1, ...]``). Only core WPILib packages built by mostrobotics can be specified here; vendor packages must be listed in ``requires``. ``requires`` is a list of strings, and each item is equivalent to a line of a [requirements.txt](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file. You can install any pure python packages on the roboRIO and they will likely work, but any packages that have binary dependencies must be cross-compiled for the roboRIO. For example, if you needed to use ``numpy`` in your robot code: diff --git a/source/docs/software/vscode-overview/3rd-party-libraries.rst b/source/docs/software/vscode-overview/3rd-party-libraries.rst index e91279f359..1a1de995cb 100644 --- a/source/docs/software/vscode-overview/3rd-party-libraries.rst +++ b/source/docs/software/vscode-overview/3rd-party-libraries.rst @@ -42,10 +42,10 @@ Vendor dependencies are installed on a per-project basis (so each robot project .. tab-item:: Python :sync: python - All RobotPy project dependencies are specified in ``pyproject.toml``. You can add additional vendor-specific dependencies either by: + All RobotPy project dependencies are specified in ``pyproject.toml``. You can add additional dependencies by: - * Adding the component name to ``components`` - * Adding the PyPI package name to ``requires`` + * Adding WPILib component names to ``components`` (for core WPILib packages only) + * Adding PyPI package names to ``requires`` (for vendor packages and other dependencies) .. seealso:: :doc:`/docs/software/python/pyproject_toml` @@ -65,29 +65,29 @@ Vendor dependencies are installed on a per-project basis (so each robot project | XRP | xrp | robotpy-xrp | +----------+------------+---------------------+ - Optional vendor-specific components (not all are available at the beginning of the season): - - +---------------------+-----------+-------------+---------------------------+ - | | Origin | components | requires | - +=====================+===========+=============+===========================+ - | ChoreoLib | Vendor | | sleipnirgroup-choreolib | - +---------------------+-----------+-------------+---------------------------+ - | CTRE Phoenix 6 | Vendor | phoenix6 | phoenix6 | - +---------------------+-----------+-------------+---------------------------+ - | CTRE Phoenix 5 | Community | phoenix5 | robotpy-ctre | - +---------------------+-----------+-------------+---------------------------+ - | PathPlannerLib | Vendor | pathplannerlib | robotpy-pathplannerlib | - +---------------------+-----------+-------------+---------------------------+ - | PhotonVision | Vendor | photonvision | photonlibpy | - +---------------------+-----------+-------------+---------------------------+ - | Playing With Fusion | Community | playingwithfusion | robotpy-playingwithfusion | - +---------------------+-----------+-------------+---------------------------+ - | REVLib | Community | rev | robotpy-rev | - +---------------------+-----------+-------------+---------------------------+ - | Studica | Community | navx | robotpy-navx | - +---------------------+-----------+-------------+---------------------------+ - | URCL | Community | | robotpy-urcl | - +---------------------+-----------+-------------+---------------------------+ + Vendor packages (not all are available at the beginning of the season): + + +---------------------+-----------+---------------------------+ + | | Origin | requires | + +=====================+===========+===========================+ + | ChoreoLib | Vendor | sleipnirgroup-choreolib | + +---------------------+-----------+---------------------------+ + | CTRE Phoenix 6 | Vendor | phoenix6 | + +---------------------+-----------+---------------------------+ + | CTRE Phoenix 5 | Community | robotpy-ctre | + +---------------------+-----------+---------------------------+ + | PathPlannerLib | Vendor | robotpy-pathplannerlib | + +---------------------+-----------+---------------------------+ + | PhotonVision | Vendor | photonlibpy | + +---------------------+-----------+---------------------------+ + | Playing With Fusion | Community | robotpy-playingwithfusion | + +---------------------+-----------+---------------------------+ + | REVLib | Community | robotpy-rev | + +---------------------+-----------+---------------------------+ + | Studica | Community | robotpy-navx | + +---------------------+-----------+---------------------------+ + | URCL | Community | robotpy-urcl | + +---------------------+-----------+---------------------------+ When using ``requires``, you can specify a version by appending ``==`` to the package name, e.g. ``robotpy-commands-v2==2024.0.0``. If you do not specify a version, the latest version will be installed. @@ -155,4 +155,4 @@ Vendor dependencies are installed on a per-project basis (so each robot project .. tab-item:: Python :sync: python - Third party libraries are packaged into Python wheels and uploaded to PyPI (if pure python) and/or WPILib's artifactory. Users can enable them as dependencies either by adding the component name to ``components`` (recommended) or by adding an explicit dependency for the PyPI package in ``requires``. The dependencies are downloaded when ``robotpy sync`` is executed, and installed on the roboRIO when ``robotpy deploy`` is executed. + Third party libraries are packaged into Python wheels and uploaded to PyPI (if pure python) and/or WPILib's artifactory. Core WPILib packages can be installed by adding the component name to ``components``, while vendor packages must be added to ``requires`` with their PyPI package name. The dependencies are downloaded when ``robotpy sync`` is executed, and installed on the roboRIO when ``robotpy deploy`` is executed. From 20414edca919f203d1d18749dc85c1840abfea9a Mon Sep 17 00:00:00 2001 From: jasondaming Date: Fri, 10 Oct 2025 20:55:24 -0500 Subject: [PATCH 3/4] Remove internal implementation detail about mostrobotics Per review feedback, users don't need to know this internal detail --- source/docs/software/python/pyproject_toml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/docs/software/python/pyproject_toml.rst b/source/docs/software/python/pyproject_toml.rst index cfb244570f..de6dbce583 100644 --- a/source/docs/software/python/pyproject_toml.rst +++ b/source/docs/software/python/pyproject_toml.rst @@ -40,7 +40,7 @@ Each of the following will instruct the deploy process to install packages to th ``robotpy_version`` is the version of the ``robotpy`` PyPI package that this robot code depends on. -``components`` defines which optional core WPILib packages should be installed (equivalent to ``pip install robotpy[component1, ...]``). Only core WPILib packages built by mostrobotics can be specified here; vendor packages must be listed in ``requires``. +``components`` defines which optional core WPILib packages should be installed (equivalent to ``pip install robotpy[component1, ...]``). Only core WPILib packages can be specified here; vendor packages must be listed in ``requires``. ``requires`` is a list of strings, and each item is equivalent to a line of a [requirements.txt](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file. You can install any pure python packages on the roboRIO and they will likely work, but any packages that have binary dependencies must be cross-compiled for the roboRIO. For example, if you needed to use ``numpy`` in your robot code: From d451c6c059b71c3691777255468f2983dd15176f Mon Sep 17 00:00:00 2001 From: jasondaming Date: Mon, 13 Oct 2025 20:14:15 -0500 Subject: [PATCH 4/4] Clarify that components is only for core WPILib packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review feedback, updated documentation to make it clear that: - 'components' is ONLY for core WPILib packages built by WPILib - ALL vendor packages must be specified in 'requires' Changes: - Added important note emphasizing the distinction - Removed 'components' column from WPILib components table - Updated vendor packages table header to clarify these use 'requires' - Updated pyproject.toml example to show vendor packages in 'requires' only - Removed vendor packages from components list in example 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../docs/software/python/pyproject_toml.rst | 21 +++++----- .../vscode-overview/3rd-party-libraries.rst | 38 ++++++++++--------- 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/source/docs/software/python/pyproject_toml.rst b/source/docs/software/python/pyproject_toml.rst index de6dbce583..028c49c77e 100644 --- a/source/docs/software/python/pyproject_toml.rst +++ b/source/docs/software/python/pyproject_toml.rst @@ -16,24 +16,27 @@ The ``pyproject.toml`` file looks something like this: [tool.robotpy] # Version of robotpy this project depends on robotpy_version = "2024.2.1.0" -# Which extra RobotPy components should be installed +# Which core WPILib components should be installed # -> equivalent to `pip install robotpy[extra1, ...] components = [ # "all" # "apriltag" # "commands2" # "cscore" - # "navx" - # "pathplannerlib" - # "phoenix5" - # "phoenix6" - # "playingwithfusion" - # "rev" # "romi" # "sim" + # "xrp" +] +# Other pip packages to install (including vendor packages) +requires = [ + # Vendor packages (examples): + # "robotpy-navx" + # "robotpy-pathplannerlib" + # "robotpy-ctre" # Phoenix 5 + # "phoenix6" + # "robotpy-playingwithfusion" + # "robotpy-rev" ] -# Other pip packages to install -requires = [] ``` Each of the following will instruct the deploy process to install packages to the roboRIO: diff --git a/source/docs/software/vscode-overview/3rd-party-libraries.rst b/source/docs/software/vscode-overview/3rd-party-libraries.rst index 1a1de995cb..c70575a7ce 100644 --- a/source/docs/software/vscode-overview/3rd-party-libraries.rst +++ b/source/docs/software/vscode-overview/3rd-party-libraries.rst @@ -44,31 +44,33 @@ Vendor dependencies are installed on a per-project basis (so each robot project All RobotPy project dependencies are specified in ``pyproject.toml``. You can add additional dependencies by: - * Adding WPILib component names to ``components`` (for core WPILib packages only) - * Adding PyPI package names to ``requires`` (for vendor packages and other dependencies) + * Adding WPILib component names to ``components`` (for core WPILib packages built by WPILib only) + * Adding PyPI package names to ``requires`` (for all vendor packages and other dependencies) + + .. important:: Only core WPILib packages can be specified in ``components``. All vendor packages must be listed in ``requires``. .. seealso:: :doc:`/docs/software/python/pyproject_toml` - Optional WPILib components: + Optional WPILib components (use ``components``): - +----------+------------+---------------------+ - | | components | requires | - +==========+============+=====================+ - | Apriltag | apriltag | robotpy-apriltag | - +----------+------------+---------------------+ - | Commands | commands2 | robotpy-commands-v2 | - +----------+------------+---------------------+ - | cscore | cscore | robotpy-cscore | - +----------+------------+---------------------+ - | Romi | romi | robotpy-romi | - +----------+------------+---------------------+ - | XRP | xrp | robotpy-xrp | - +----------+------------+---------------------+ + +----------+------------+ + | | components | + +==========+============+ + | Apriltag | apriltag | + +----------+------------+ + | Commands | commands2 | + +----------+------------+ + | cscore | cscore | + +----------+------------+ + | Romi | romi | + +----------+------------+ + | XRP | xrp | + +----------+------------+ - Vendor packages (not all are available at the beginning of the season): + Vendor packages (use ``requires``, not all are available at the beginning of the season): +---------------------+-----------+---------------------------+ - | | Origin | requires | + | | Origin | PyPI Package Name | +=====================+===========+===========================+ | ChoreoLib | Vendor | sleipnirgroup-choreolib | +---------------------+-----------+---------------------------+