Biçim Rehberi

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

Dosya İsimleri

Yalnızca küçük alfanümerik karakterler ve - (eksi) sembolünü kullanın.

Yazılım / Donanım ile ilgili belgeler için, belge adının sonuna “Hardware” veya “Software” ekleyin. Örneğin, ultrasonik donanım.rst

.Rst uzantısına sahip suffix dosya adları.

Not

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

Metin

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

Bu terimler için aşağıdaki örnekleri kullanın:

  • roboRIO (RoboRIO, roboRio yada RoboRio değil)

  • LabVIEW (labview yada LabView değil)

  • Visual Studio Code (VS Code) (vscode, VScode, vs code, v.b. değil)

  • macOS (Mac OS, Mac OSX, Mac OS X, Mac, Mac OS, v.b. değil)

  • GitHub (github, Github vb. Değil)

  • PowerShell (powershell, Powershell vb. Değil)

  • Linux (linux değil)

  • Java (java değil)

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.

Dosya adları, foksiyon ve değişken adları için genel geçer değerleri kullanın.

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 FRC Sözlüğü. You can reference items in the glossary by using :term:`deprecated`.

Whitespace - Beyazboşluk

Girinti

Yeni bir içerik bloğu oluşturmadığınız sürece girinti her zaman önceki girinti düzeyiyle eşleşmelidir.

İçerik direktiflerinin yeni satırının ..toctree:: olarak girintisi 3 boşluk olmalıdır.

Boş Satırlar

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.

İç Beyazboşluk

Cümleler arasında bir boşluk kullanınız.

Başlıklar

Headings should be in the following structure.

  1. # for document titles. Do not use this more than once per article.

  2. ## for document sections

  3. ### for document sub-sections

  4. #### for document sub-sub-sections

  5. Daha düşük seviyelerde bir yapı kullanmanız gerekirse, bir şeyleri yanlış yapıyorsunuz demektir.

Ana başlıklar için başlığı kullanın.

Listeler

Listelerin her girinti düzeyi arasında yeni bir satır olması gerekir. En yüksek girinti 0 girintiye sahip olmalı ve sonraki alt listeler, önceki girintinin ilk karakterinden başlayan bir girintiye sahip olmalıdır.

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

Kod Blokları

Tüm kod bloklarının belirtilmiş bir dili olmalıdır.

```python
print("Hello!")

import antigravity
```

  1. İstisna: Biçimlendirmenin korunması gereken ve dili olmayan içerik. Bunun yerine metin kullanın.

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/v2026.2.1/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/v2026.2.1/wpilibcExamples/src/main/cpp/examples/GettingStarted/cpp/Robot.cpp
   :language: c++
   :lines: 50-60
   :lineno-match:

.. remoteliteralinclude:: https://raw.githubusercontent.com/robotpy/examples/242924b3843fdcc6efc2cefa8eac7bfff8b6bc48/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.

Not

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/v2026.2.1/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.

Tavsiyeler

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.

Kullanın

.. warning:: This is a warning!

Yanlış

.. warning::
   This is a warning!

Resimler

Görseller, içerik ve yönergeyi ayıran 1 yeni satırla oluşturulmalıdır.

Tüm görseller (vektörler dahil) boyut olarak 500 kilobayttan daha küçük olmalıdır. Lütfen daha küçük bir çözünürlük ve daha verimli sıkıştırma algoritmaları kullanın.

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

Resim dosyaları

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

Resim adları, görüntünün ne gösterdiğinin kısa bir açıklaması olduğu short-description.png adlandırma şemasına uymalıdırlar. Bu, 24 karakterden az olmalıdır.

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

Not

Erişilebilirlik önemlidir! Resimler bir :alt: direktifiyle işaretlenmelidir.

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

Vectorel Resimler

SVG dosyaları svg2pdfconverter Sphinx uzantısı ile desteklenir.

Bunları başka herhangi bir resim dosyasında yaptığınız gibi kullanın.

Not

Vektördeki gömülü görüntülerin vektörü 500KB sınırını aşacak şekilde şişirmediğinden emin olun.

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

Draw.io Diyagramları

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.

Bunları başka herhangi bir vektör görüntüsü veya başka bir görüntü gibi kullanın.

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

Draw.io Dosyaları

Draw.io dosyaları, normal resimler ile neredeyse aynı adlandırma düzenini izler. Gömülü .drawio meta verisine sahip dosyaları takip etmek için, dosya adının sonuna, uzantının önüne bir .drawio ekleyin, yani dosyanın adı document-title-1.drawio.svg vb olmalıdır. Ek olarak, diyagramlar belge dizininde diagrams adlı bir alt klasörde saklanmalıdır.

Bir diyagramı meta verilerle .svg olarak kaydetmenin ayrıntıları için, buraya bakınız Draw.io Kaydetme Talimatları.

Uyarı

Draw.io dışında herhangi bir programda diagrams klasöründe bulunan veya .drawio.svg ile biten herhangi bir dosyayı değiştirmediğinizden emin olun, aksi takdirde dosyanın meta verilerini kırma riskiniz olabilir. , bu dosyayı düzenlenemez hale getirebilir.

Dosya uzantları

Dosya uzantıları kod biçimlendirmesi kullanmalıdır. Örneğin, şunu kullanın:

``.png``

Onun yerine

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

İçindekiler (TOC-Table of Contents)

Her kategori bir index.rst içermelidir. Bu dizin dosyası, maxdepth maksimum derinliği 1 içermelidir. Alt kategoriler maxdepth 1 ile kabul edilebilir.

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

Örnekler

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

Önemli Not!

Bu liste kapsamlı değildir ve yöneticiler değişiklik yapma hakkını saklı tutar. Değişiklikler bu belgeye yansıtılacaktır.