格式指南

本文档包含针对frc-docs项目的各种RST / Sphinx特定准则。有关与各种WPILib代码项目相关的指南,请参见`the WPILib GitHub <https://github.com/wpilibsuite/styleguide>`__

文件名

仅使用小写字母数字字符和``-‘’(减号)。

对于具有相同软件/硬件名称的文档,请在文档名称的末尾附加“硬件”或“软件”。 IE,``超声波-hardware.rst’’

后缀名为.rst的文件名。

注解

如果您在编辑扩展名为.rst的文件时遇到问题,建议使用的文本编辑器为`Notepad ++ <https://notepad-plus-plus.org/>`__。请确保`tabs are replaced with spaces <https://stackoverflow.com/questions/455037/convert-tabs-to-spaces-in-notepad>`__,并将空格缩进设置为``3’’ 。

页面引用

页面引用将根据页面文件名和部分标题自动生成。

例如,给定以下文件``contributing.rst’’和一个名为``页面引用’’的部分,您可以通过执行``:ref:`contributing:Page References```来引用此内容。

注解

请注意,文档结构保留在引用中,其根是conf.py文件的位置。要访问子文件夹中的文档,只需在文件名之前添加文件夹路径即可。 IE,:ref:`docs/software/sensors/ultrasonics-sensors:Ultrasonics - Sensors`

文本

所有文本内容应在同一行上,如果需要可读性,请使用编辑器的自动换行功能。

对于这些术语,请依据以下情况:

  • roboRIO (不是 RoboRIO、 roboRio或 RoboRio)

  • LabVIEW (不是 labview 或 LabView)

  • Visual Studio Code (VS Code) (而非 vscode、 VScode、 vs code, etc)

  • macOS (而非 Mac OS, Mac OSX, Mac OS X, Mac, Mac OS, etc.)

  • GitHub (不是 github, Github, etc)

  • PowerShell (不可用 powershell, Powershell, etc)

  • Linux (不可用 linux)

  • Java (不可用 java)

将ASCII字符集用于英语文本。对于特殊字符(例如希腊符号),请使用标准字符实体集`standard character entity sets <https://docutils.sourceforge.io/docs/ref/rst/definitions.html#character-entity-sets>`_。

对单个方程式使用”.. math ::”,对于行内方程式使用’’:math:’’。可以在`here <https://www.reed.edu/academic_support/pdfs/qskills/latexcheatsheet.pdf>`_找到有用的LaTeX公式备忘单。

对于文件名,函数和变量名,请使用文字。

注册商标的使用* FIRST * |reg|和FRC \ |reg|应遵循 `this page <https://www.firstinspires.org/brand>`__中的政策。具体而言,在可能的情况下(即不嵌套在其他标记中或文档标题中),商标的首次使用应使用 |reg| 符号,并且*FIRST*的所有实例均应以斜体显示。 |reg|可以通过在文档顶部使用``.. include:: <isonum.txt>`` ,然后使用``*FIRST*|reg|`` 或 ``FRC|reg|``来添加符号。

常用术语应添加到docs / software / frc-glossary:FRC术语表中。您可以通过使用:term:`deprecated`来引用词汇表中的项目。

空白

缩进

缩进应该*始终*匹配先前的缩进级别*除非*正在创建新的内容块。

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

空行

基本文本块和章节标题之间应有“ 1”空白行。 *应当*分隔文本块和内容指令的空白行应为“ 1”。

内部空白

段落中使用一个空格。

标题

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

  1. ``=``用于文档标题。 每篇文章的使用次数*不得*超过*一次*。

  2. ``-‘’用于文档章节

  3. ``^``用于文档子章节

  4. “~”代表文档子子章节

  5. 如果您需要使用任何较低级别的结构,那么您应该有些事情出错了。

标题使用标题大小写字体。

列表

列表在每个缩进级别之间应有一个新行。最高的缩进应具有``0’’缩进,并且随后的子列表应具有从前一个缩进的第一个字符开始的缩进。

- Block one
- Block two
- Block three

  - Sub 1
  - Sub 2

- Block four

代码块

所有代码块都应指定一种编程语言。

  1. 例外:必须保留格式且没有编程语言的内容。使用``text’’代替。

对于C ++和Java示例代码,请遵循`WPILib style guide <https://github.com/wpilibsuite/styleguide/>`_ 。例如,在C ++和Java中使用两个空格进行缩进。

警告

警告(在`here <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__列出)的文字应与警告本身位于同一行。但是,当警告中包含多个内容部分时,此规则也有例外。通常,建议不要在一条警告中包含多个内容部分。

用途

.. warning:: This is a warning!

.. warning::
   This is a warning!

图片

图像应使用“ 1”新行,将内容和指令分隔开。

所有图像(包括矢量)的大小应小于``500’’kb字节。请使用较小的分辨率和更有效的压缩算法。

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

图片文档

图像文件应存储在文档目录中的``document-name/images’’子目录中

他们应遵循``short-description.png’’的命名方案,其中图像名称是对图像显示内容的简短描述。该字符应少于``24’’个字符。

它们应该是.png或.jpg图片扩展名。出于存储和可访问性的考虑,.gif是不可接受的。

注解

可访问性很重要!图像应该用``:alt:``指令标记。

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

矢量图

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

就像使用其他任何图像一样,只需简单地使用它们即可。

注解

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

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

Draw.io图

Draw.io(也称为`diagrams.net <https://app.diagrams.net/>`__)图通过嵌入了.drawio元数据的``svg``文件来支持,从而允许``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的细节,请查看:ref:docs/contributing/frc-docs/drawio-saving-instructions:Draw.io Saving Instructions

警告

确保不修改“diagrams”文件夹中的任何文件或在draw.io以外的任何程序中以.drawio.svg结尾的文件,否则可能会破坏文件的元数据,使其无法编辑。

文档扩展名

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

``.png``

代替:

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

目录(TOC)

每个类别都应包含一个“ index.rst”。该索引文件应包含``1’’的``maxdepth’’。子类别是可接受的,只要``maxdepth’’为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!

务必留意!

此列表并不详尽,管理员保留进行更改的权利。更改将反映在本文档中。