[WPILib Blog] From ScreenSteps to frc-docs

Posted on the WPILib Blog, 5/20/2020: https://wpilib.org/blog/from-screensteps-to-frc-docs

frc-docs is the official source of tutorials and documentation for the FIRST Robotics Competition control system. frc-docs started as a community-led project toward the end of the 2019 season. The goals of the new system were to:

  • Support community contributions to the documentation
  • Allow the documentation to be versioned
  • Facilitate translations

frc-docs was inspired by the RobotPy documentation and quickly took on a similar model using a system composed of Sphinx and ReadTheDocs. There was one large issue with the migration that had to get solved first. ScreenSteps articles did not contain any form of a source that could be migrated, so each article would need to be ported by hand. This was a painstaking process of copying each articles’ text and formatting it to be compatible with the Sphinx system. This work was split up among numerous community members and would not have been possible without them.

Documentation Features

frc-docs makes use of Sphinx and ReStructuredText to achieve many different features that previously were not possible.

LaTeX Math

The documentation previously made use of static images to showcase mathematical equations. Sphinx allows us to embed math in the LaTeX format for a much better output. Using the Sphinx extension MathJax additionally allows us to share the original LaTeX without visiting the source repository.

Code Tabs

One feature that makes documentation immensely cleaner is code tabs. Instead of having separate sections for Java and C++ articles, there is a single article with different tabs for each language. This allows for deduplicating a large number of articles.

Warnings

ReStructuredText offers directives called “Admonitions”. Admonitions can be used to highlight portions of text that are particularly important. These can be warnings, information blocks, danger blocks, etc. This allows for a much cleaner view of particular portions of text in the documentation.

Changes for 2021

New features, articles, and changes are continuously pushed to the frc-docs repository. You can always view the latest version of the documentation by using the left sidebar version menu over at https://docs.wpilib.org/. The current URL will redirect to the “stable” 2020 version of the documentation, so you’ll need to manually navigate to the latest version.

Glossary Terms

Glossary terms are a feature of ReStructuredText that allows for special handling of vocabulary terms. This provides links to terms throughout the documentation. One feature currently being investigated is the ability to see a term’s definition on mouse hover. A preview of this feature can be shown in the image below.

Vector images

Since frc-docs is stored on version control (Git), binary images take up a large amount of space. Recently, we’ve started supporting Scalable Vector Graphics (SVG). Vector graphics are fantastic as they allow the images to be changed easily and are stored in a small file size. As we migrate to vector graphics we can increase the quality of images such as sensor hardware. Special thanks to Benjamin Antupit of FRC 4990 for contributing many excellent vector images such as the one shown below.

Translations

Perhaps the most exciting new feature of frc-docs is the ability for community translations. frc-docs makes use of Transifex to allow an easy way to contribute translations. These translations are then reviewed and merged to the main frc-docs repository, immediately becoming live on the website. You may have already noticed that we are trialing Spanish translations on the documentation.

How to help

frc-docs is open source under Creative Commons at WPILib Github organization (https://github.com/wpilibsuite/frc-docs). There is extensive documentation on the build system we use for the documentation over on the website (https://docs.wpilib.org/en/latest/docs/contributing/frc-docs/index.html). See the translation article for information on how to contribute translations.

We’d like to thank all the contributors to the frc-docs project. You can see a list of contributors here.

28 Likes

I wrote this :slight_smile:

8 Likes

Are the base vector images for all of the control system components available somewhere?

So far, I’ve been modifying and adding to the vector images from this great diagram by @stefenacepcion. I would be happy to put together a package of all of the common control system component vectors. PM me if you’re interested.

1 Like

I think it would be awesome to have those images out there and available for teams to use in their own diagrams.

Totally agreed. Do you (or anyone else) have a preference for formats? I have most of them currently as vector images, so they could be distributed as svg or png files. Would you (or anyone else) be interested in a library of icons for diagrams.net (formerly draw.io) or a library for a different schematic program?

It is currently also in the frc-docs source at https://github.com/wpilibsuite/frc-docs/blob/master/source/docs/getting-started/getting-started-frc-control-system/images/control-system-hardware/FRC-Control-System-Layout.svg

1 Like

I do think this would be useful but the individual components as images separated out would be nice to have.

Sounds good. I’ll work on a few things and post in this thread when it’s ready to share. Might be a week or so (since my school is still in session online) before I have time to get to it, but it’s on my list. Thanks for asking @marshall!

1 Like