wpilibsuite / frc-docs

Official FRC Documentation powered by Read the Docs

frc-docs

Welcome to frc-docs! This repository contains the various source articles for the frc-docs website. frc-docs is licensed under Creative Commons, with assets such as the FIRST logo under trademark and copyright of FIRST.

The website is available under the following domains, it is preferred to use the WPILib domain URL:

• https://docs.wpilib.org/en/latest/
• https://frcdocs.wpi.edu/en/latest/
• https://frc-docs.readthedocs.io/en/latest/

WPILib Mission

The WPILib Mission is to enable FIRST Robotics teams to focus on writing game-specific software rather than focusing on hardware details - "raise the floor, don't lower the ceiling". We work to enable teams with limited programming knowledge and/or mentor experience to be as successful as possible, while not hampering the abilities of teams with more advanced programming capabilities. We support Kit of Parts control system components directly in the library. We also strive to keep parity between major features of each language (Java, C++, and NI's LabVIEW), so that teams aren't at a disadvantage for choosing a specific programming language. WPILib is an open source project, licensed under the BSD 3-clause license. You can find a copy of the license here.

Contributing to frc-docs

We're happy to have you contributing to frc-docs, whether it's; writing articles, fixing code, new extensions, or adding translations!

All the information needed to contribute to frc-docs is located in the contributing section on frc-docs. Additionally, please ensure that all contributions follow the WPILib Code of Conduct.

frc-docs's Issues

ScreenSteps Comment: Listening for value changes

https://github.com/wpilibsuite/frc-docs/blob/develop/source/docs/software/networktables/listening-for-change.rst

The catch of an InterruptedException should include Thread.currentThread().interrupt();

SmartDashboard - LiveWindow needs a port

https://wpilib.screenstepslive.com/s/currentCS/m/smartdashboard/c/92707 needs a port

Link to Github Issues

Should definitely put a link in the sidebar for reporting issues with docs.

PIDSubsystem Clairifcation

In the article: https://frc-docs.readthedocs.io/en/develop/docs/software/commandbased/pid-subsystems-commands.html#using-a-pidsubsystem

The class with signature public class ShooterSubsystem extends SynchronousPIDSubsystem does not have a member m_shooter as referenced in the sample below the class, reporduced here:

// Spin up the shooter when the 'A' button is pressed
driverController.getButton(Button.kA.value)
    .whenPressed(new InstantCommand(m_shooter::enable, m_shooter));

What is m_shooter and where does enable come from?

Set standards on WPI supported hardware documentation

It needs to be decided on what documentation in terms of hardware is allowed. I can understand a vendor bias needs to be avoided as much as possible, but this may limit available docs for some commonly used equipment. Also, details regarding allowed images would be fantastic.

The current approach is, KOP equipment only (apart from conflicting documentation of third-party equipment that was on screensteps???).

As for images, any images taken locally or part of Creative Commons.

@Kevin-OConnor

CAN Addressing should be in an advanced section

CAN Device Addressing should be in some sort of advanced or vendor specific section. It's not for general team usage.

Broken Link on driver-station

https://github.com/wpilibsuite/frc-docs/blob/develop/source/docs/software/getting-started/driver-station.rst

Has a broken link to installing_FRC_update_suite

Labview Section needs to be ported

https://wpilib.screenstepslive.com/s/currentCS/m/labview
needs a port

Enable Linkcheck

I think it'll be beneficial in the long run to enable this check. It'll require some amount of configuration and tweaking to the docs to getting it run reliably (ignore anchor points in URLs, and ignore localhost URLs). Fortunately, Sphinx actually has linkcheck pretty well documented.

Pros: We know when a link will break.
Cons: All PRs will fail when a link breaks.

Migrate the software installation guides

Flesh out basic programming and advanced programming sections

These sections should include a guide on various basic FRC tutorials as related to FRC

• PID (oblarg?)
• Feedforward (oblarg?)
• Controlling various robot components (elevator, shooter, etc)

Update pages to follow style guide

Various pages are outdated and poorly formatted.

Setup custom URL

Build example code

We should build all of the code examples so that when something changes in WPILib, we know that the documentation needs to be updated. What is the best way to do this? Could we use the samples directory already in allwpilib and then as part of the build bring allwpilib in? I really have no idea what is best to do.

ScreenSteps Comment: Reading array values published by NetworkTables

https://github.com/wpilibsuite/frc-docs/blob/develop/source/docs/software/vision-processing/grip/reading-array-values-published-by-networktables.rst

NetworkTable.getTable() no longer exists. This method will no longer work. Must use NetworkTableInstance.

Java code tabs should be first

Java should be the first and default tab for all code blocks because it is the most popular language by a significant amount.

Add page detailing community resources

Since this is an excellent resource towards the the software and electronics components for FRC, it seems logical that it might also provide a stepping off point towards other community resources and assistance, particularly ones that provide real time (or quick) responses to individual questions, as this isn't something well suited to a static site.

Potential examples of resources that might be highlighted are the FRC Discord (particularly the #programming-discussion and #programming-help channels), Chief Delphi's Programming category, and The Compass Alliance's Call Center.

There would also likely need to be some sort of disclaimer on these.

Add [Deprecated] Command-Based docs

Still supported, albeit deprecated. I'll end up doing this in the next few days or so.

Document PCM and pneumatics

Transfering these docs to MD: https://wpilib.screenstepslive.com/s/currentCS/m/java/l/599708-operating-pneumatic-cylinders-solenoids

I can copy paste C++ code, but can't write it. I'll need some help with that part.

Add documentation on how to set up AzureCI for CI builds

Low on the priority list, but it gets asked often enough it would be work doing as part of the simulation work.

"Installing C++ and Java Development Tools"

Transferring these docs to Markdown.
https://wpilib.screenstepslive.com/s/currentCS/m/java/l/1027503-installing-c-and-java-development-tools-for-frc

ScreenSteps Comment: Programming your radio

https://github.com/wpilibsuite/frc-docs/blob/develop/source/docs/software/getting-started/radio-programming.rst

In the yellow box describing the update from 19.1.0 to 19.1.1, it says "Teams should install the new version, then re-program their radio (their is no need to re-flash the firmware)". The word "their" should be "there".

Finish system overview sections

Merge system overview into "one article" with multiple "chapters"?

Update all links where possible to https

As it says on the tin. We should check all the links in the project and see if any can be updated to https especially with all the work that has been done on that front recently.

DriverStation log viewer needs to be ported

https://wpilib.screenstepslive.com/s/currentCS/m/driver_station/l/144980-driver-station-log-file-viewer needs a port. There's a pull-request open but I believe that's stale.

Clean up networking documentation

There is a lot of overlap in the networking documents. Clean up/combine so that the right things are split in the right places.

C++ example in Accelerometers - Software

See the digital linear filters snippet.
https://frc-docs.readthedocs.io/en/develop/docs/software/sensors/accelerometers-software.html#using-accelerometers-in-code

"Binding a command to a joystick button" contains errors

The section Binding a command to a joystick button has a few flaws

• The Joystick classes getButton() method is deprecated and only return a boolean of the state.
• The XboxController classes getButton() method does not even exist.
• Both the Joystick and XboxController classes enum Button is private

Taking these into account the code shown for binding appears to be incorrect. If these are features that will be added in the future this should likely be noted in the docs.

roboRIO in Titles

When roboRIO is used in titles the first r should be lower case.

Document the Actuator section of screensteps

Clean up all of Getting Started

Getting Started needs some hefty cleanup in the source, as well as links.

Remove manual references and replace with auto references

All references created using

.. _reference-name-here:

Should be removed since this could conflict with the autoreference-label extension.

Complete sensor hardware stubs

Sensor hardware needs to be filled out

Reorganize TOCs

Current structure breaks topics between software, hardware, and networking. See PDF output.

Figure out a new nesting scheme for nested TOCs

Add Google Analytics

Add analytics to track page views

Add clarification that the FIRST logo is not Creative Commons

FIRST logo is not creative commons, and that should be specified somewhere

Port Shuffleboard Advanced section

Shuffleboard advanced section is still missing: https://wpilib.screenstepslive.com/s/currentCS/m/shuffleboard/c/235105

Not sure that "advanced applications" is the right title for all of these, either some should move or the section should be renamed.

• Displaying camera streams
• Working with graphs
• Using record and playback
• Working with Commands and Subsystems
• Testing and tuning PID loops
• Viewing hierarchies of data

Add RobotBuilder pages

https://wpilib.screenstepslive.com/s/currentCS/m/robotbuilder

Hardware Documentation Rewrite

The hardware section is severely poor. The images are unclear, the language is confusing, and other such problems. Unfortunately, I don't have quite the knowledge to rewrite these articles. Contributors welcome!

Specify dependency versions

Probably be a good idea to specify the exact dependency versions we want to use. That way nothing randomly breaks because of an unexpected update.

Update Contribution Guidelines to include link to WPILib Mission statement

It can be found here: https://github.com/wpilibsuite/allwpilib/blob/master/README.md

We also probably need to update the mission statement but we can do that later.

Update azure build status in readme

https://dev.azure.com/wpilib/Documentation/_apis/build/status/wpilibsuite.frc-docs?branchName=master

ScreenSteps Comment: Using multiple cameras

https://github.com/wpilibsuite/frc-docs/blob/develop/source/docs/software/vision-processing/introduction/using-multiple-cameras.rst

I don't have an error to report, but I was wondering if you had an example of this for Java.

Tutorial on SendableChooser

This might exist on ScreenSteps already. Should be investigated either way.

Set up framework for multiple languages

I think it'll be fantastic if contributors can translate the docs into their language of choice. This will also for FIRST/WPILib resources to be expanded beyond the normal supported languages.

https://docs.readthedocs.io/en/stable/guides/manage-translations.html

Remove references to frc/WPILib.h

There are some code snippets throughout the docs (copied from screensteps) that reference WPILib.h

These will need to be updated following WPILib.h deprecation, see wpilibsuite/allwpilib#1779

List of TODOs - Contributors welcome!

This is being posted here for the sake of not having to create a commit on master every time I want to edit something.

Please read the style and contributing guide for opening a pull request.
https://frc-docs.readthedocs.io/en/develop/contributing.html

Getting started with the control system
OPEN - 2018 Game Data Details

[Other KOP Resources]

• In progress by @firecrafty

Test Mode

• Available

LabView examples should use VI snippets

This would enable example screenshots to be directly copied and pasted into LabView as code.

See http://www.ni.com/tutorial/9330/en/

Enforce EOL @ EOF

We should enforce EOL @ EOF as part of the build process so we do not get commit noise.

(end of line @ end of file)

Add C++ examples

Some C++ code snippets/examples are missing throughout the docs. This is a result of the screensteps just not having some C++ snippets. Probably should get added at some point.