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 (GitHub - wpilibsuite/frc-docs: Official FRC Documentation powered by Read the Docs). There is extensive documentation on the build system we use for the documentation over on the website (Contributing to frc-docs — FIRST Robotics Competition documentation). 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.
