Skip to content

Commit b95aea2

Browse files
virtualdvirtuald
authored
Merge pull request #66 from robotpy/2024-updates
Initial 2024 updates
2 parents 6019b0d + eca17a1 commit b95aea2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+185
-3031
lines changed

‎.readthedocs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sphinx:
66
build:
77
os: ubuntu-22.04
88
tools:
9-
python: "3.10"
9+
python: "3.11"
1010

1111
python:
1212
install:

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ become increasingly more difficult to introduce all of the pieces to new
66
users. This is the foundation for a unified documentation site for all
77
RobotPy projects, in hopes of reducing that confusion.
88

9+
Now that Python is an officialy supported language, this site still aims to unify the various API documentation for RobotPy projects. However, much of our documentation has been moved to the [WPILib documentation](https://docs.wpilib.org).
10+
911
All of our documentation is built using Sphinx, and is hosted at
1012
http://robotpy.readthedocs.io/
1113

‎conf.py

Lines changed: 41 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,9 @@
7070
copyright = f"2014-{date.today().year}, RobotPy development team"
7171

7272

73+
frc_docs = "https://docs.wpilib.org/en/stable"
74+
7375
intersphinx_mapping = {
74-
"commandsv1": (
75-
"https://robotpy.readthedocs.io/projects/commands-v1/en/%s/" % rtd_version,
76-
None,
77-
),
7876
"commandsv2": (
7977
"https://robotpy.readthedocs.io/projects/commands-v2/en/%s/" % rtd_version,
8078
None,
@@ -83,40 +81,60 @@
8381
"https://robotpy.readthedocs.io/projects/pyfrc/en/%s/" % rtd_version,
8482
None,
8583
),
86-
"ntcore": (
87-
"https://robotpy.readthedocs.io/projects/pyntcore/en/%s/" % rtd_version,
88-
None,
89-
),
90-
"wpilib": (
91-
"https://robotpy.readthedocs.io/projects/wpilib/en/%s/" % rtd_version,
92-
None,
93-
),
94-
"hal": (
95-
"https://robotpy.readthedocs.io/projects/hal/en/%s/" % rtd_version,
84+
"robotpy": (
85+
"https://robotpy.readthedocs.io/projects/robotpy/en/%s/" % rtd_version,
9686
None,
9787
),
9888
"robotpy_ext": (
9989
"https://robotpy.readthedocs.io/projects/utilities/en/%s/" % rtd_version,
10090
None,
10191
),
102-
"cscore": (
103-
"https://robotpy.readthedocs.io/projects/cscore/en/%s/" % rtd_version,
104-
None,
105-
),
106-
"frc": ("https://docs.wpilib.org/en/stable", None),
92+
"frc": (frc_docs, None),
10793
}
10894

10995
redirects = {
96+
"getting_started": f"{frc_docs}/docs/zero-to-robot/introduction.html",
11097
"2020_notes": "upgrade_notes.html",
111-
"install/pynetworktables": "pyntcore.html"
98+
"install/pynetworktables": "pyntcore.html",
99+
"frameworks/command": f"{frc_docs}/docs/software/commandbased/",
100+
"guide/anatomy": f"{frc_docs}/docs/zero-to-robot/step-4/creating-test-drivetrain-program-cpp-java-python.html",
101+
"guide/index": f"{frc_docs}/docs/software/python/",
102+
"guide/deploy": f"{frc_docs}/docs/software/python/subcommands/deploy.html",
103+
"guide/examples": "https://github.com/robotpy/examples",
104+
"guide/guidelines": "guidelines",
105+
"guide/nt": f"{frc_docs}/docs/software/networktables/index.html",
106+
"guide/running": f"{frc_docs}/docs/software/python/subcommands/index.html",
107+
"guide/python": "https://docs.python-guide.org/en/latest/intro/learning/",
108+
"guide/simulator": f"{frc_docs}/docs/software/wpilib-tools/robot-simulation/introduction.html",
109+
"guide/testing": "testing",
110+
"hw": f"{frc_docs}/docs/hardware/hardware-basics/index.html",
111+
"install/computer": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
112+
"install/components": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
113+
"install/packages": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
114+
"install/robot": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
115+
"install/commands": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
116+
"install/cscore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
117+
"install/ctre": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
118+
"install/navx": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
119+
"install/pathplannerlib": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
120+
"install/pwfusion": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
121+
"install/pyfrc": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
122+
"install/pyntcore": f"{frc_docs}/docs/zero-to-robot/step-2/python-setup.html",
123+
"install/rev": f"{frc_docs}/docs/software/vscode-overview/3rd-party-libraries.html",
124+
"vision/code": f"{frc_docs}/docs/software/vision-processing/index.html",
125+
"vision/index": f"{frc_docs}/docs/software/vision-processing/index.html",
126+
"vision/other": f"{frc_docs}/docs/software/vision-processing/index.html",
127+
"vision/roborio": f"{frc_docs}/docs/software/vision-processing/roborio/index.html",
112128
}
113129

114130
# The version info for the project you're documenting, acts as replacement for
115131
# |version| and |release|, also used in various other places throughout the
116132
# built documents.
117133
#
118134
# The short X.Y version.
119-
version = subprocess.check_output(("git", "describe", "--tags"), text=True).split(".")[0]
135+
version = subprocess.check_output(("git", "describe", "--tags"), text=True).split(".")[
136+
0
137+
]
120138
# The full version, including alpha/beta/rc tags.
121139
release = version
122140

@@ -133,15 +151,7 @@
133151

134152
# The theme to use for HTML and HTML Help pages. See the documentation for
135153
# a list of builtin themes.
136-
html_theme = "default"
137-
138-
if not on_rtd: # only import and set the theme if we're building docs locally
139-
import sphinx_rtd_theme
140-
141-
html_theme = "sphinx_rtd_theme"
142-
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
143-
else:
144-
html_theme = "default"
154+
html_theme = "sphinx_rtd_theme"
145155

146156
# Output file base name for HTML help builder.
147157
htmlhelp_basename = "RobotPy"
@@ -187,7 +197,7 @@
187197
epub_title = "RobotPy"
188198
epub_author = "RobotPy development team"
189199
epub_publisher = "RobotPy development team"
190-
epub_copyright = "2014-2022, RobotPy development team"
200+
epub_copyright = "2014-2024, RobotPy development team"
191201

192202
# A list of files that should not be packed into the epub file.
193203
epub_exclude_files = ["search.html"]

‎dev/deploy.rst

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,26 @@
44
Deploy process details
55
======================
66

7-
When the code is uploaded to the robot, the following steps occur:
7+
TODO
88

9-
* SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!)
10-
* pyfrc does some checks to make sure the environment is setup properly
11-
* The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py``
12-
* The files ``robotCommand`` and ``robotDebugCommand`` are created
13-
* ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched
9+
..
10+
This is mostly the same, but has a lot of additional steps as of 2024
1411
15-
If you wish for the code to be started up when the roboRIO boots up, you need to
16-
make sure that "Disable RT Startup App" is **not** checked in the roboRIO's web
17-
configuration.
12+
When the code is uploaded to the robot, the following steps occur:
1813

19-
These steps are compatible with what C++/Java does when deployed by GradleRIO,
20-
so you should be able to seamlessly switch between python and other FRC
21-
languages!
14+
* SSH/sftp operations are performed as the ``lvuser`` user (this is REALLY important, don't use the ``admin`` user!)
15+
* robotpy-installer does some checks to make sure the environment is setup properly
16+
* The directory containing ``robot.py`` is recursively copied to the the directory ``/home/lvuser/py``
17+
* The files ``robotCommand`` and ``robotDebugCommand`` are created
18+
* ``/usr/local/frc/bin/frcKillRobot.sh -t -r`` is called, which causes any existing robot code to be killed, and the new code is launched
19+
20+
If you wish for the code to be started up when the roboRIO boots up, you need to
21+
make sure that "Disable RT Startup App" is **not** checked in the roboRIO's web
22+
configuration.
23+
24+
These steps are compatible with what C++/Java does when deployed by GradleRIO,
25+
so you should be able to seamlessly switch between python and other FRC
26+
languages!
2227

2328
.. _manual_code_deploy:
2429

@@ -67,16 +72,12 @@ Example code:
6772
6873
print(data)
6974
70-
if __name__ == "__main__":
71-
wpilib.run(MyRobot)
72-
73-
7475
How to manually run code
7576
------------------------
7677

7778
.. note:: Generally, you shouldn't need to use this process.
7879

79-
If you don't have (or don't want) to install pyfrc, running code manually is
80+
If you don't have (or don't want) to install robotpy-installer, running code manually is
8081
pretty simple too.
8182

8283
1. Make sure you have RobotPy installed on the robot
@@ -86,10 +87,10 @@ pretty simple too.
8687

8788
::
8889

89-
python3 robot.py run
90+
python3 -m robotpy run
9091

9192
Your driver station should be able to connect to your code, and it will be able
9293
to operate your robot!
9394

9495
.. note:: This is good for running experimental code, but it won't start the
95-
code when the robot starts up. Use pyfrc to do that.
96+
code when the robot starts up. Use robotpy-installer to do that.

‎dev/design.rst

Lines changed: 3 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,52 +3,7 @@ Design
33

44
.. _robotpy_extension_options:
55

6-
Adding options to robot.py
7-
--------------------------
6+
Adding options to the ``robotpy`` command
7+
-----------------------------------------
88

9-
When :func:`wpilib.run` is called, that function determines available commands
10-
that can be run, and parses command line arguments to pass to the commands.
11-
Examples of commands include:
12-
13-
* Running the robot code
14-
* Running the robot code, connected to a simulator
15-
* Running unit tests on the robot code
16-
* And lots more!
17-
18-
python setuptools has a feature that allows you to extend the commands available
19-
to robot.py without needing to modify WPILib's code. To add your own command,
20-
do the following:
21-
22-
* Define a setuptools entrypoint in your package's setup.py (see below)
23-
* The entrypoint name is the command to add
24-
* The entrypoint must point at an object that has the following properties:
25-
* Must have a docstring (shown when ``--help`` is given)
26-
* Constructor must take a single argument (it is an argparse parser which options can be added to)
27-
* Must have a 'run' function which takes two arguments: options, and robot_class. It must
28-
also take arbitrary keyword arguments via the ``**kwargs`` mechanism. If it receives arguments
29-
that it does not recognize, the entry point must ignore any such options.
30-
31-
If your command's run function is called, it is your command's responsibility
32-
to execute the robot code (if that is desired). This sample command
33-
demonstrates how to do this::
34-
35-
class SampleCommand:
36-
'''Help text shown to user'''
37-
38-
def __init__(self, parser):
39-
pass
40-
41-
def run(self, options, robot_class, **static_options):
42-
# runs the robot code main loop
43-
robot_class.main(robot_class)
44-
45-
To register your command as a robotpy extension, you must add the following
46-
to your setup.py setup() invocation::
47-
48-
from setuptools import setup
49-
50-
setup(
51-
...
52-
entry_points={'robotpy': ['name_of_command = package.module:CommandClassName']},
53-
...
54-
)
9+
As of 2024 the ``robotpy`` command (also accessed via ``python -m robotpy``) is located in the `robotpy-cli <https://github.com/robotpy/robotpy-cli>`__ package. Instructions for adding custom subcommands is located in the README file.

‎faq.rst

Lines changed: 29 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Installing and Running RobotPy
2727
How do I install RobotPy?
2828
~~~~~~~~~~~~~~~~~~~~~~~~~
2929

30-
See our :ref:`getting started guide <getting_started>`.
30+
RobotPy installation documentation is now at :doc:`frc-docs <frc:docs/zero-to-robot/step-2/python-setup>`.
3131

3232
What version of Python do RobotPy projects use?
3333
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -38,8 +38,8 @@ documentation <https://docs.python.org/3/>`__ instead of the Python
3838
2.x documentation.
3939

4040
- RobotPy WPILib on the roboRIO uses the latest version of Python 3 at kickoff.
41-
In 2023, this was Python 3.11. When using pyfrc or similar projects,
42-
you should use a Python 3.7 or newer interpreter (the latest is recommended).
41+
In 2024, this was Python 3.12. When using pyfrc or similar projects,
42+
you should use a Python 3.8 or newer interpreter (the latest is recommended).
4343
- RobotPy 2014.x is based on Python 3.2.5.
4444

4545
`pynetworktables <https://github.com/robotpy/pynetworktables>`__ is
@@ -71,15 +71,19 @@ Prior to 2015, the API matched the C++ version of WPILib.
7171
Is Command-based programming available?
7272
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7373

74-
Of course! Check out the :mod:`commands2 <commands2>` package. There
75-
is also some :ref:`python-specific documentation available <command_framework_docs>`.
74+
Of course! Check out the :mod:`commands2 <commands2>` package.
7675

77-
Is there an easy way to test my code outside of the robot?
78-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76+
Are Vendor libraries available?
77+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7978

80-
Glad you asked! Our pyfrc project has a built in :ref:`lightweight robot simulator <simulator>`
81-
you can use to run your code, and also has builtin support for unit testing
82-
with `py.test <http://pytest.org>`_.
79+
We encourage vendors to make Python versions of their libraries available. Since
80+
Python support has only been official since 2024, not all vendors do this. If
81+
you are a vendor, please reach out to our team and we'd be happy to assist.
82+
83+
The RobotPy project also provides unofficial wrappers for vendor libraries that don't
84+
take a lot of effort to create and maintain.
85+
86+
.. seealso:: :doc:`frc:docs/software/vscode-overview/3rd-party-libraries`
8387

8488
Competition
8589
-----------
@@ -89,46 +93,19 @@ Competition
8993
Is RobotPy competition-legal?
9094
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9195

92-
Python is not an official FRC language yet, but we are working with
93-
the WPILib team to make it official in 2024. See
94-
https://wpilib.org/blog/bringing-python-to-frc for the announcement.
95-
96-
As RobotPy was not written by anyone involved with the GDC, we can't
97-
provide a guaranteed answer (particularly not for future years).
98-
However, we see no reason that RobotPy would not be legal: to the
99-
cRIO/RoboRIO, it looks just like any other C++ WPILib-using program that
100-
reads text files. RobotPy itself should be considered COTS software as
101-
it is freely available to all teams. Teams have been using RobotPy since
102-
2010 without any problems from FIRST, and we expect that to continue.
103-
104-
Caveat emptor: while RobotPy is almost certainly legal to use, your team
105-
should carefully consider the risk of using such a large piece of
106-
unofficial software; unless RobotPy is used by many teams, if you run
107-
into trouble at a competition, there may not be anyone else there to
108-
help! However, we've found that most problems teams run into are
109-
problems with WPILib itself, and not RobotPy.
110-
111-
Also, be sure to keep in mind the fact that Python is a dynamic language
112-
and is NOT compiled. This means that typos can easily go undetected
113-
until your robot runs that particular line of code, resulting in an
114-
exception and 5 second restart. Make sure to test your code thoroughly
115-
(see our :ref:`unit testing documentation <unit_tests>`).
116-
96+
As of 2024, Python is officially supported for use in FRC.
11797

11898
.. _is_stable:
11999

120100
Is RobotPy stable?
121101
~~~~~~~~~~~~~~~~~~
122102

123-
Yes! While Python is not an officially supported language, teams have been
103+
Yes! Teams have been
124104
using RobotPy since 2010, and the maintainer of RobotPy is a member of the
125105
WPILib team. Much of the time when bugs are found, they are found in the
126106
underlying WPILib, instead of RobotPy itself.
127107

128-
One caveat to this is that because RobotPy doesn't have a beta period like
129-
WPILib does, bugs tend to be found during the first half of competition season.
130-
However, by the time build season ends, RobotPy is just as stable as any of
131-
the officially suported languages.
108+
One caveat to this is that because RobotPy is not yet widely adopted, bugs tend to be found during the first half of competition season. However, by the time build season ends, RobotPy is just as stable.
132109

133110
How often does RobotPy get updated?
134111
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -170,8 +147,17 @@ Ross Light, FRC Team 973. Peter is a member of the FIRST WPILib team,
170147
and also created the `ntcore <https://github.com/wpilibsuite/ntcore/>`_
171148
and `cscore <https://github.com/wpilibsuite/cscore/>`_ libraries.
172149

173-
The current RobotPy maintainer is `Dustin
174-
Spicuzza <http://github.com/virtuald>`_, also a member of the FIRST WPILib team.
150+
How is RobotPy different from WPILib?
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+
All current RobotPy developers are members of the FIRST WPILib team, so in some sense RobotPy is a subgroup of WPILib. However, RobotPy is still separate from WPILib in many ways and has it's own shiny logo, but as time goes on we are aiming to integrate more into the greater WPILib whole.
154+
155+
One thing that makes RobotPy different from WPILib is that we also maintain separate libraries for interacting with various 3rd party vendors, but we expect as Python gets more traction in FRC that vendors will develop and maintain their own libraries.
156+
157+
Who develops RobotPy?
158+
---------------------
159+
160+
The current RobotPy maintainer is `Dustin Spicuzza <http://github.com/virtuald>`_.
175161

176162
Current RobotPy developers include:
177163

@@ -186,6 +172,7 @@ RobotPy is an open project that all members of the FIRST community can
186172
easily and quickly contribute to. If you find a bug, or have an idea
187173
that you think others can use:
188174

175+
- Add Python documentation to :doc:`the official WPILib documentation <frc:index>`
189176
- Test and report any issues you find.
190177
- Port and test a useful library.
191178
- Write a Python module and share it with others (and contribute it to

0 commit comments

Comments
 (0)