格式指南
本文档包含针对frc-docs项目的各种RST / Sphinx特定准则。有关与各种WPILib代码项目相关的指南,请参见`the WPILib GitHub <https://github.com/wpilibsuite/styleguide>`__
文件名
仅使用小写字母数字字符和``-‘’(减号)。
对于具有相同软件/硬件名称的文档,请在文档名称的末尾附加“硬件”或“软件”。 IE,``超声波-hardware.rst’’
后缀名为.rst的文件名。
备注
If you are having issues editing files with the .rst
extension, the recommended text editor is VS Code with the rST extension.
文本
All text content should be on the same line. If you need readability, use the word-wrap function of your editor.
对于这些术语,请依据以下情况:
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个空格。
空行
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.
内部空白
段落中使用一个空格。
标题
标题应采用以下结构。标题下划线应与标题本身匹配相同数量的字符。
``=``用于文档标题。 每篇文章的使用次数*不得*超过*一次*。
``-‘’用于文档章节
``^``用于文档子章节
“~”代表文档子子章节
如果您需要使用任何较低级别的结构,那么您应该有些事情出错了。
标题使用标题大小写字体。
列表
列表在每个缩进级别之间应有一个新行。最高的缩进应具有``0’’缩进,并且随后的子列表应具有从前一个缩进的第一个字符开始的缩进。
- Block one
- Block two
- Block three
- Sub 1
- Sub 2
- Block four
代码块
所有代码块都应指定一种编程语言。
例外:必须保留格式且没有编程语言的内容。使用``text’’代替。
对于C ++和Java示例代码,请遵循`WPILib style guide <https://github.com/wpilibsuite/styleguide/>`_ 。例如,在C ++和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:
.. 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
.
警告
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.
用途
.. warning:: This is a warning!
不
.. warning::
This is a warning!
链接
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 Build Instructions 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!
但是,在某些必须多次引用同一链接情况下,则接受以下语法。
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.
图片文档
Image files should be stored in the document directory, sub-directory of document-name/images
.
他们应遵循``short-description.png’’的命名方案,其中图像名称是对图像显示内容的简短描述。该字符应少于``24’’个字符。
它们应该是.png或.jpg图片扩展名。出于存储和可访问性的考虑,.gif是不可接受的。
矢量图
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。
The category index.rst
file can then be added to the root index file located at source/index.rst
.
示例
Title
=====
This is an example article
.. code-block:: java
System.out.println("Hello World");
Section
-------
This is a section!
务必留意!
此列表并不详尽,管理员保留进行更改的权利。更改将反映在本文档中。