Guía de Estilo

This document contains the various MD and RST/Sphinx specific guidelines for the frc-docs project. For guidelines related to the various WPILib code projects, see the WPILib GitHub

Nombres de Archivo

Use solo caracteres alfanuméricos en minúsculas y el guion (signo «-«).

Para documentos que tendrán un nombre de software/hardware idéntico, agregue «hardware» o «software» al final del nombre del documento. p.ej. ultrasonics-hardware.rst

Añada la extensión .rst como sufijo a los nombres de archivo.

Nota

If you are having issues editing files with the .rst extension, the recommended text editor is VS Code with the reStructuredText extension.

Texto

All text content should be on the same line. If you need readability, use the word-wrap function of your editor.

Use el siguiente caso para estos términos:

roboRIO (no RoboRIO, roboRio, o RoboRio)
LabVIEW (no labview o LabView)
Visual Studio Code (VS Code) (no vscode, VScode, vs code, etc)
macOS (no Mac OS, Mac OSX, Mac OS X, Mac, Mac OS, etc.)
GitHub (no github, Github, etc.)
PowerShell (no PowerShell, Powershell, etc.)
Linux (no linux)
Java (no Java)

Use the ASCII character set for English text. For special characters (e.g. Greek symbols) use the standard character entity sets.

Use .. math:: for standalone equations and :math: for inline equations. A useful LaTeX equation cheat sheet can be found here.

Use literales para nombres de archivos, funciones y nombres de variables.

Use of the registered trademarks FIRST® and FRC® should follow the Policy from this page. Specifically, where possible (i.e. not nested inside other markup or in a document title), the first use of the trademarks should have the ® symbol and all instances of FIRST should be italicized. The ® symbol can be added by using .. include:: <isonum.txt> at the top of the document and then using *FIRST*\ |reg| or FRC\ |reg|.

Commonly used terms should be added to the Glosario de FRC. You can reference items in the glossary by using :term:`deprecated`.

Espacios en Blanco

Sangría

La sangría debe siempre coincidir con el nivel anterior de sangría a menos que esté creando un nuevo bloque de contenido.

La sangría de las directivas de contenido como nueva línea .. toctree:: debe ser 3 espacios.

Líneas En Blanco

There should be 1 blank line separating basic text blocks and section titles. There should be 1 blank line separating text blocks and content directives.

Espacio blanco interior

Use solo uno espacio entre frases.

Títulos

Headings should be in the following structure.

# for document titles. Do not use this more than once per article.
## for document sections
### for document sub-sections
#### for document sub-sub-sections
Si necesita usar niveles más inferiores para la estructura, está haciéndolo mal.

Escriba las primeras letras de cada palabra en mayúsculas para los títulos.

Listas

Las listas deben tener una nueva línea entre cada nivel de sangría. El mayor nivel de sangría debe tener una sangría de «0», y las subsiguientes sublistas deben tener una sangría que comience en el primer carácter de la sangría anterior.

- Block one
- Block two
- Block three
  - Sub 1
  - Sub 2
- Block four

Bloques de código

Todos los bloques de código deben tener un lenguaje especificado.

```python
print("Hello!")

import antigravity
```

Excepción: Contenido donde el formato debe ser preservado y no tiene lenguaje. En lugar de eso, usa «texto».

Follow the WPILib style guide for C++ and Java example code. For example, use two spaces for indentation in C++ and Java.

RLI (Remote Literal Include)

When possible, instead of using code blocks, an RLI should be used. This pulls code lines directly from GitHub, most commonly using the example programs. This automatically keeps the code up to date with any changes that are made. The format of an RLI is:

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.1.1-beta-2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/gettingstarted/Robot.java
   :language: java
   :lines: 19-25
   :lineno-match:

.. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.1.1-beta-2/wpilibcExamples/src/main/cpp/examples/GettingStarted/cpp/Robot.cpp
   :language: c++
   :lines: 50-60
   :lineno-match:

.. remoteliteralinclude:: https://raw.githubusercontent.com/robotpy/examples/c6d0540b01e138725fad7366ff4e317e9994b78b/GettingStarted/robot.py
   :language: python
   :lines: 12-29
   :lineno-match:

Make sure to link to the raw version of the file on GitHub. There is a handy Raw button in the top right corner of the page.

Nota

RLIs should use a tag instead of main to ensure the documentation isn’t broken the next time there is a change to the RLIed code. If a tag hasn’t been created, use the full (40 character) commit hash.

Tabs

To create code tabs in an article, you can use the .. tab-set-code:: directive. You can use md style ``` codeblocks and rli directives inside. The format is:

.. tab-set-code::
   .. remoteliteralinclude:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2025.1.1-beta-2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/gettingstarted/Robot.java
      :language: java
      :lines: 19-25
      :lineno-match:

   ```c++
   // Start the timer.
   m_timer.Start();
   // Send Field2d to SmartDashboard.
   frc::SmartDashboard::PutData(&m_field);
   // Reset the drivetrain's odometry to the starting pose of the trajectory.
   m_drive.ResetOdometry(m_trajectory.InitialPose());
   // Send our generated trajectory to Field2d.
   m_field.GetObject("traj")->SetTrajectory(m_trajectory);
   ```

If you need to use more than one tab per language, multiple RLIs per language, or text tabs, you can use the .. tab-set:: and .. tab-item:: directive. The format is:

.. tab-set::
   .. tab-item:: Title
      :sync: sync-id
         Content

This example uses the sync argument to allow all of the tabs with the same key to be synced together. This means that when you click on a tab, all of the tabs with the same key will open.

If you have a mix of tab-set and tab-set-code directives on a page, you can sync them by setting the sync id on the tab-item directives to tabcode-LANGUAGE. For example, a java tab would have a sync id of tabcode-java.

Amonestaciones

Admonitions (list here) should have their text on the same line as the admonition itself. There are exceptions to this rule, however, when having multiple sections of content inside of an admonition. Generally having multiple sections of content inside of an admonition is not recommended.

Uso

.. warning:: This is a warning!

NO

.. warning::
   This is a warning!

Links

Internal Links

Internal Links will be auto-generated based on the ReStructuredText filename and section title.

For example, here are several ways to link to sections and documents.

Use this format to reference a document section. You must use the absolute path of the document. :ref:`docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics` renders to Ultrasónicos analógicos.

Use this format to reference a section of the same document. Note the single underscore. `Images`_ renders to Images.

Use this format to reference the top-level of a document. You can use relative paths :doc:`build-instructions` renders to Instrucciones de Construcción Or to use absolute paths, put a forward slash at the beginning of the path :doc:`/docs/software/hardware-apis/sensors/ultrasonics-software` renders to Ultrasónicos - Software. Note that the text rendered is the main section title of the target page regardless of the target filename.

When using :ref: or :doc: you may customize the displayed text by surrounding the actual link with angle brackets <> and adding the custom text between the first backtick ` and the first angle bracket <. For example :ref:`custom text <docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics>` renders to custom text.

External Links

It is preferred to format external links as md style hyperlinks.

Hi there, [this is a link](https://example.com) and it's pretty cool!

Sin embargo, en algunos casos en que el mismo enlace debe ser referenciado varias veces, se acepta la sintaxis que figura a continuación.

Hi there, `this is a link`_ and it's pretty cool!
..  _this is a link: https://example.com

Python API Links

Links to the RobotPY API documentation should use the following sphinx python syntax (example linking to the DriverStation API docs).

:external:py:class:`Python <robotpy:wpilib.DriverStation>`

This expands to be equivalent to:

[Python](https://robotpy.readthedocs.io/projects/robotpy/en/stable/wpilib/DriverStation.html#wpilib.DriverStation)

Imágenes

Las imágenes deben ser creadas con 1 línea que separe el contenido y la directiva.

Todas las imágenes (incluyendo los vectores) deben tener un tamaño inferior a «500» kilobytes. Por favor, utilice una resolución más pequeña y algoritmos de compresión más eficientes.

.. image:: images/my-article/my-image.png
   :alt: Always add alt text here describing the image.

Archivos de imágenes

Image files should be stored in the document directory, sub-directory of document-name/images.

Deben seguir el esquema de nomenclatura de descripción-corta.png, donde el nombre de la imagen es una breve descripción de lo que muestra la imagen. Debe tener menos de 24 caracteres.

Deben tener la extensión de imagen .png or .jpg. .gif es inaceptable debido a problemas de almacenamiento y accesibilidad.

Nota

¡La accesibilidad es importante! Las imágenes deben estar marcadas con una directiva :alt:.

.. image:: images/my-document/my-image.png
   :alt: An example image

Imágenes vectoriales

Los archivos SVG son soportados a través de la extensión Sphinx de svg2pdfconverter.

Simplemente úsalos como lo harías con cualquier otra imagen.

Nota

Asegúrate de que las imágenes incrustadas en el vector no inflen el vector hasta superar el límite de 500KB.

.. image:: images/my-document/my-image.svg
   :alt: Always add alt text here describing the image.

Diagramas Draw.io

Draw.io (also known as diagrams.net) diagrams are supported through svg files with embedded .drawio metadata, allowing the svg file to act as a source file of the diagrams, and to be rendered like a normal vector graphics file.

Simplemente úsalos como lo harías con cualquier otra imagen vectorial, o cualquier otra imagen.

.. image:: diagrams/my-document/diagram-1.drawio.svg
   :alt: Always add alt text here describing the image.

Archivos de Draw.io

Los archivos Draw.io siguen casi el mismo esquema de nombres que las imágenes normales. Para llevar un registro de los archivos que tienen los metadatos .drawio incrustados, agrega un .drawio al final del nombre del archivo, antes de la extensión, lo que significa que el nombre del archivo debe ser document-title-1.drawio.svg y así sucesivamente. Además, los diagramas deben ser almacenados en el directorio de documentos en una subcarpeta llamada diagramas.

Para los detalles de guardar un diagrama como un .svg con metadatos, echa un vistazo a Draw.io Instrucciones de Guardado.

Advertencia

Asegúrate de que no modificas ningún archivo que esté en una carpeta diagramas, o que termine en .drawio.svg en cualquier otro programa que no sea draw.io, de lo contrario podrías arriesgarte a romper los metadatos del archivo, haciéndolo ineditable.

Extensiones de archivo

Las extensiones de archivo deben usar el formato de código. Por ejemplo, use:

``.png``

en lugar de:

.png
".png"
"``.png``"

Tablas de contenido (TDC)

Cada categoría debe contener un «índice.rst». Este archivo de índice debe contener una «profundidad máxima» de «1». Las subcategorías son aceptables, con una profundidad máxima de 1.

The category index.rst file can then be added to the root index file located at source/index.rst.

Ejemplos

# Title
This is an example article
```java
System.out.println("Hello World");
```
## Section
This is a section!

¡Nota importante!

Esta lista no es exhaustiva y los administradores se reservan el derecho de hacer cambios. Los cambios se reflejarán en este documento.