样式指南#

本文件包含了6940swerve-docs项目的各种RST/Sphinx具体准则。

文件名#

仅使用小写字母数字字符和 - （减号）符号。

对于会有一个相同的软件/硬件名称的文件，在文件名的后面加上 “硬件 “或 “软件”。例如， ultrasonics-hardware.rst 。

文件名后缀为 .rst 。

备注

如果你在编辑以 .rst 为扩展名的文件时遇到问题，推荐的文本编辑器是 Notepad++ 。请确保 tabs被替换为空格，并且空格缩进被设置为 3 。

文本#

所有文本内容应在同一行，如果你需要可读性，可使用编辑器的换字功能。

对这些术语使用以下情况。

roboRIO(不是RoboRIO、roboRio或RoboRio)
LabVIEW(不是labview或LabView)
Visual Studio Code（VS Code）（不是vscode、VScode、vs code等）。
macOS（不是Mac OS、Mac OSX、Mac OS X、Mac、Mac OS等）。
GitHub（不是github，Github，等）。
PowerShell（不是powershell、Powershell等）
Linux（不是linux）
Java（不是java）

对英文文本使用ASCII字符集。对于特殊字符（如希腊符号），使用标准字符实体集。

独立方程使用 ...math:: ，内联方程使用 :math: 。一个有用的LaTeX方程小抄可以在这里找到。

对文件名、函数和变量名使用字面意义。

空白#

缩进#

缩进应*始终*与之前的缩进程度相一致，除非*你正在创建一个新的内容块。

作为新行的内容指令的缩进 ...toctree:: 应该是 3 个空格。

空白线#

基本文本块和章节标题之间应该有 1 空行。在文本块*和*内容指令之间应该有 1 空行。

内部空白#

句子之间使用一个空格。

标题#

标题应采用以下结构。标题的下划线应与标题本身的字符数相同。

= 用于文件标题。不要在每篇文章中使用超过一次。
- 为文件章节
^ 用于文件分节
~ 用于文件分节的分节
如果你需要使用任何更低层次的结构，你就会做错事。

标题使用标题大小写。

列表#

列表在每个缩进级别之间都应该有一个新的行。最高的缩进应该有 0 的缩进，随后的子列表应该有一个从上一个缩进的第一个字符开始的缩进。

- Block one
- Block two
- Block three

  - Sub 1
  - Sub 2

- Block four

代码块#

所有的代码块都应该有一个指定的语言。

例外：必须保留格式且没有语言的内容。请使用 text 代替。

遵循 WPILib风格指南的C++和Java示例代码。例如，在C++和Java中使用两个空格来缩进。

RLI（远程字面意思包含）。#

如果可能的话，应该使用RLI，而不是使用代码块。这直接从GitHub上拉取代码行，最常见的是使用示例程序。这将自动保持代码的更新，以适应任何变化。 RLI的格式是：

.. group-tab:: Java

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

.. group-tab:: C++

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

注意，需要使用group-tab而不是code-tab。还要确保链接到GitHub上的原始版本文件，在页面的右上角有一个方便的 “Raw “按钮。

警告#

警告（列出此处）的文字应与警告本身在同一行。然而，当警告中包含多个部分的内容时，这一规则也有例外。一般来说，不建议在告诫中包含多个部分的内容。

使用这个

.. warning:: This is a warning!

而不是使用这个

.. warning::
   This is a warning!

链接#

内部链接#

内部链接将根据ReStructuredText文件名和章节标题自动生成。

例如，这里有几种链接到章节和文件的方法。

使用这种格式来引用同一文件的一个部分。注意单个下划线。`Images`_ 渲染为 Images 。

使用这种格式来引用一个文件的顶层。你可以使用相对路径 :doc:`translation` 渲染为翻译或者使用绝对路径，在路径的开头加一个正斜杠 :doc:`/docs/about/about` 渲染为关于这个文档。注意，渲染的文本是目标页面的主要部分标题，与目标文件名无关。

当使用 :ref: 或 :doc: 时，你可以通过用角括号 <> 包围实际的链接，并在第一个后缀 ` 和第一个角括号 < 之间添加自定义文本来定制显示文本。例如 :ref:`custom text <docs/software/hardware-apis/sensors/ultrasonics-software:Analog ultrasonics>` 渲染为 custom text 。

外部链接#

最好将外部链接格式化为匿名的超链接。需要注意的是两个附加在文本上的下划线。在只使用一个下划线的情况下，编译文件时可能会出现问题。

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

然而，在某些情况下，同一个链接必须被多次引用，下面的语法能够被接受。

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

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

图片#

在创建图片时，应在内容和指令之间加入``1`` 新行。

所有图片（包括矢量）的大小应小于 500 KB。请使用较小的分辨率和更有效的压缩算法。

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

图像文件#

图片文件应该存储在文档目录下，即 文档名/图片 的子目录下。

它们应该遵循 short-description.png 的命名方案，其中图片的名称是对图片内容的简短描述。这应该少于 24 个字符。

它们应该是 .png 或 .jpg 的图像扩展。.gif 是不可接受的，因为存储和可访问性的问题。

备注

可访问性是很重要的!图片应该用 :alt: 指令来标记。

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

矢量图像#

SVG文件通过 svg2pdfconverter Sphinx扩展支持。

只需像使用任何其他图像一样使用它们即可。

备注

确保矢量中的任何嵌入式图像不会使矢量膨胀到超过500KB的限制。

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

Draw.io 图形#

Draw.io（也被称为 diagrams.net）图表通过 svg 文件支持，其中嵌入了 .drawio 元数据，允许 svg 文件作为图表的源文件，并像普通的矢量图形文件一样被渲染。

只需像使用任何其他矢量图像或任何其他图像一样使用它们。

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

Draw.io 文件#

Draw.io文件几乎遵循与普通图片相同的命名方案。为了跟踪那些嵌入了 .drawio 元数据的文件，在文件名的末尾、扩展名之前加上 .drawio ，这意味着文件名应该是 document-title-1.drawio.svg ，以此类推。此外，图表应该存储在文档目录下一个名为 diagrams 的子文件夹中。

关于将图表保存为带有元数据的 ``.svg `` 的具体细节，请看 docs/contributing/frc-docs/drawio-saving-instructions:Draw.io Saving Instructions 。

警告

确保你不要在draw.io以外的任何程序中修改 diagrams 文件夹中的任何文件，或以 .drawio.svg 结尾的文件，否则你可能有破坏文件元数据的风险，使其无法使用。

文件扩展名#

文件扩展名应使用代码格式。例如，使用。

``.png``

而不是：

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

目录（TOC）#

每个类别应包含一个 index.rst' 。这个索引文件应该包含一个 最大深度 为 1 的文件。子类别是可以接受的，最大深度 为1。

然后可以将类别 index.rst 文件添加到位于 source/index.rst 的根索引文件中。

实例#

Title
=====
This is an example article

.. code-block:: java

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

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

重要提示!#

这份清单并不详尽并且管理员仍保留修改的权利。变化将反映在本文件中。