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çinDaha 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.