Guia de Estilo

Este documento contém as várias diretrizes específicas do RST/Sphinx para o projeto frc-docs. Para orientações relacionadas aos vários projetos de código WPILib, consulte o WPILib GitHub

Nomes dos Arquivos

Use apenas caracteres alfanuméricos minúsculos e o símbolo - (menos).

Para documentos que terão um nome de software/hardware idêntico, acrescente «Hardware» ou «Software» no final do nome do documento. Por exemplo, ultrasonics-hardware.rst

Sufixo dos nomes dos arquivos com a extensão .rst.

Nota

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

Texto

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

Use os seguintes casos para estes termos:

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

Use o conjunto de caracteres ASCII para textos em inglês. Para caracteres especiais (por exemplo, símbolos gregos), use os conjuntos de entidades de caracteres padrão.

Use .. math:: para equações independentes e :math: para equações inline. Uma folha de dicas de equação LaTeX útil pode ser encontrada aqui.

Use literais para nomes de arquivos, funções e nomes de variáveis.

Uso das marcas registradas FIRST® and FRC® deve seguir a Política desta página:. Especificamente, onde possível (ou seja, não aninhado dentro de outra marcação ou no título de um documento), o primeiro uso das marcas registradas deve ter o símbolo ® e todas as instâncias de FIRST devem estar em itálico. O símbolo ® pode ser adicionado usando .. include:: <isonum.txt> no topo do documento, e então usando *FIRST*\ |reg| ou FRC\ |reg|.

Termos usados frequentemente devem ser adicionados ao FRC Glossary. Você pode referenciar itens no glossário usando :term:`deprecated`.

Espaço em Branco

Recuo

O recuo deve sempre corresponder ao nível anterior de recuo, a menos que você esteja criando um novo bloco de conteúdo.

O recuo das diretivas de conteúdo como uma nova linha .. toctree:: deve ser 3 espaços.

Linhas em Branco

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.

Espaço em Branco Interno

Use um espaço entre as frases.

Títulos

Títulos devem estar na seguinte estrutura. Os sublinhados do título devem corresponder ao mesmo número de caracteres que o próprio título.

= para títulos de documentos. Não use isso mais de uma vez por artigo.
- para seções de documento
^ para subseções do documento
~ para sub-subseções do documento
Se você precisar usar outros níveis inferiores de estrutura, você está fazendo coisas erradas.

Deixe a primeira letra de cada palavra maiúscula para títulos.

Listas

As listas devem ter uma nova linha entre cada nível de recuo. O recuo mais alto deve ter recuo 0, e as sublistas subsequentes devem ter um recuo começando no primeiro caractere do recuo anterior.

- Block one
- Block two
- Block three

  - Sub 1
  - Sub 2

- Block four

Blocos de código

All code blocks should have a language specified.

Exception: Content where formatting must be preserved and has no language. Instead use text.

Siga o guia de estilo do WPILib para C++ e Java. Por exemplo, use dois espaços para recuo em C++ e Java.

RLI (Remote Literal Include)

Quando possível, em vez de usar blocos de código, um RLI deve ser usado. Isso extrai linhas de código diretamente do GitHub, mais comumente usando os programas de exemplo. Isso automaticamente mantém o código atualizado com quaisquer alterações feitas. O formato de um RLI é:

.. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
   :language: java
   :lines: 44-61
   :linenos:
   :lineno-start: 44

.. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibcExamples/src/main/cpp/examples/RamseteController/cpp/Robot.cpp
   :language: c++
   :lines: 18-30
   :linenos:
   :lineno-start: 18

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.

Tabs

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

.. tab-set-code::

   .. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2024.3.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
      :language: java
      :lines: 44-61
      :linenos:
      :lineno-start: 44


   .. code-block:: 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.

Advertências

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!

NÃO

.. 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 Analog ultrasonics.

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 Instruções de Construção 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 Ultrasonics - 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 anonymous hyperlinks. The important thing to note is the two underscores appending the text. In the situation that only one underscore is used, issues may arise when compiling the document.

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

However, in some cases where the same link must be referenced multiple times, the syntax below is accepted.

Hi there, `this is a link`_ and it's pretty cool!

..  _this is a link: https://example.com

Images

Images should be created with 1 new line separating content and directive.

All images (including vectors) should be less than 500 kilobytes in size. Please make use of a smaller resolution and more efficient compression algorithms.

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

Arquivos de Imagem

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

They should follow the naming scheme of short-description.png, where the name of the image is a short description of what the image shows. This should be less than 24 characters.

They should be of the .png or .jpg image extension. .gif is unacceptable due to storage and accessibility concerns.

Nota

Accessibility is important! Images should be marked with a :alt: directive.

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

Vector Images

SVG files are supported through the svg2pdfconverter Sphinx extension.

Simply use them as you would with any other image.

Nota

Ensure that any embedded images in the vector do not bloat the vector to exceed the 500KB limit.

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

Draw.io Diagrams

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.

Simply use them like you would any other vector image, or any other image.

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

Draw.io Files

Draw.io files follow almost the same naming scheme as normal images. To keep track of files that have the embedded .drawio metadata, append a .drawio to the end of the file name, before the extension, meaning the name of the file should be document-title-1.drawio.svg and so on. Additionally, diagrams should be stored in the document directory in a sub-folder named diagrams.

For the specifics of saving a diagram as a .svg with metadata, take a look at Instruções para Salvar no Draw.io.

Aviso

Make sure you don’t modify any file that is in a diagrams folder, or ends in .drawio.svg in any program other than draw.io, otherwise you might risk breaking the metadata of the file, making it uneditable.

File Extensions

File extensions should use code formatting. For example, use:

``.png``

instead of:

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

Índice

Each category should contain an index.rst. This index file should contain a maxdepth of 1. Sub-categories are acceptable, with a maxdepth of 1.

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

Examples

Title
=====
This is an example article

.. code-block:: java

   System.out.println("Hello World");

Section
-------
This is a section!

Important Note!

This list is not exhaustive and administrators reserve the right to make changes. Changes will be reflected in this document.