Biçim Rehberi

Bu belge, frc-docs projesi için çeşitli RST/Sphinx’e özgü yönergeleri içerir. Çeşitli WPILib kod projeleriyle ilgili yönergeler için bkz. 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 rST 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)

İngilizce metin için ASCII karakter kümesini kullanın. Özel karakterler için (örneğin, Yunan sembolleri) standart karakter kümelerini <https://docutils.sourceforge.io/docs/ref/rst/definitions.html#character-entity-sets> _ kullanın.

Bağımsız denklemler için .. math :: ve satır içi denklemler için : math: kullanın. Yararlı bir LaTeX denklem kısayol sayfası `şu adreste bulunabilir: <https://www.reed.edu/academic_support/pdfs/qskills/latexcheatsheet.pdf> `_.

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

Tescilli ticari markaların kullanımı FIRST ® ve FRC|reg| politikasını şu sayfadan takip etmelisiniz. Spesifik olarak, mümkün olduğunda (yani başka bir işaretlemenin içine veya bir belge başlığına yerleştirilmemişse), ticari markaların ilk kullanımında ® sembolü ve tüm FIRST yazı örnekleri italik yazılmalıdır. ® sembolü, belgenin üst kısmındaki ..include::<isonum.txt> kullanılarak ve ardından *FIRST*\| reg | veya FRC\|reg| kullanılarak eklenebilir .

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

Başlıklar aşağıdaki yapıda olmalıdır. Başlık alt çizgileri, başlığın kendisiyle aynı sayıda karakterle eşleşmelidir.

Belge başlıkları için =. Bunu makale başına * birden fazla * kullanmayın.
- doküman bölümleri için
^ alt doküman bölümleri için
~ Doküman alt-alt bölümleri için
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.

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

C ++ ve Java örnek kodu için WPILib biçim kılavuzunu takip ediniz. Örneğin, C++ ve Java’da girinti için iki boşluk kullanın.

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.

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!

Linkler

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 Derleme Yapısı 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!

Bununla birlikte, aynı bağlantıya birden çok kez başvurulması gereken bazı durumlarda, aşağıdaki sözdizimi kabul edilir.

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

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

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 (aynı zamanda diagrams.net olarak da bilinir) diyagramları, gömülü .drawio meta verisine sahip` svg dosyalarıyla desteklenir ve svg dosyası, diyagramların kaynak dosyası olarak işlev görür, normal bir vektör grafik dosyası gibi işlenir.

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

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