הנחיות סגנון
מסמך זה מכיל את ההנחיות הספציפיות של RST/Sphinx לפרויקט frc-docs. להנחיות הקשורות לפרויקטי קוד WPILib השונים, ראו את ה-GitHub של WPILib
שמות הקבצים
השתמשו רק באותיות קטנות באנגלית, במספרים, ובסימן -
(מינוס).
למסמכים בעלי שם תוכנה/חומרה זהה, הוסיפו ”Hardware“ או ”Software“ בסוף שם הקובץ. לדוגמא, ultrasonics-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, וכו׳)
macOS (לא Mac OS, Mac OSX, Mac OS X, Mac, Mac OS, וכו׳)
GitHub (לא github, Github, וכו׳)
PowerShell (לא powershell, Powershell, וכו׳)
Linux (לא linux)
Java (לא java)
השתמש בתווי ASCII לטקסט באנגלית. עבור תווים מיוחדים (למשל סמלים יווניים) השתמשו בערכות תווים סטנדרטיות
השתמשו ב-.. math::` עבור משוואות עצמאיות ו-
:math:`` למשוואות בשורה. מסמך נוסחאות LaTeX שימושי ניתן למצוא כאן.
השתמשו במילים פשוטות עבור שמות הקבצים, פונקציות ושמות משתנים.
שימוש בסימני המסחר הרשומים FIRST® ו-FRC® צריך להיות בהתאם למדיניות של דף זה. באופן ספציפי, במידת האפשר (לדוגמא לא בכותרת מסמכים), השימוש הראשון בסימני המסחר צריך להיות הסימן ® וכל ההופעות של FIRST צריכות להיות נטוייות. ניתן להוסיף את הסימן ® באמצעות .. include:: <isonum.txt>
בתחילת המסמך ואז באמצעות *FIRST*\ |reg|
או FRC\ |reg|
.
Commonly used terms should be added to the מילון מונחי FRC. You can reference items in the glossary by using :term:`deprecated`
.
Whitespace
הזחה
ההזחה תמיד צריכה להתאים לרמה הקודמת של ההזחה, אלא אם כן אתם יוצרים בלוק תוכן חדש.
Indentation of content directives as new line .. toctree::
should be 3 spaces.
שורות ריקות
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.
Whitespace פנימי
השתמשו ברווח אחד בין משפטים.
כותרות
הכותרות צריכות להיות במבנה הבא. הקו התחתון צריך להתאים למספר התווים של הכותרת עצמה.
=
לכותרות מסמכים. אל תשתמשו בזה יותר מפעם אחת לכל מאמר.-
עבור קטעי מסמך-
עבור תתי-קטע מסמך~
עבור תתי-תתי-קטע מסמךאם אתם צריכים להשתמש ברמות נמוכות יותר של מבנה, אתם עושים דברים לא נכונים.
Use title case for headings.
רשימות
לרשימות צריך להיות קו חדש בכל רמת הזחה. על רשימה הגבוהה ביותר צריכה להיות בהזחה 0
, ורשימות המשנה הבאות צריכות להיות בהזחה החל מהתו הראשון של ההזחה הקודמת.
- Block one
- Block two
- Block three
- Sub 1
- Sub 2
- Block four
בלוקי קוד
יש לציין שפה לכל בלוקי הקוד.
חריג: תוכן בו יש לשמור על עיצוב ואין לו שפה. במקום זאת השתמשו ב-
text
.
עקבו אחר הנחיות הסגנון של WPILib עבור דוגמאות קוד C ++ ו-Java. לדוגמה, יש להשתמש בשני רווחים להזחה ב-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.1.1-beta-3/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.1.1-beta-3/wpilibcExamples/src/main/cpp/examples/RamseteController/cpp/Robot.cpp
:language: cpp
: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.1.1-beta-3/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
:language: java
:lines: 44-61
:linenos:
:lineno-start: 44
.. code-block:: cpp
// 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 הנחיות בנייה 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
קילובייט. אנא השתמשו ברזולוציה קטנה יותר ובאלגוריתמי דחיסה יעילים יותר.
.. 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
אינה מקובלת בגלל חששות לאחסון ונגישות.
הערה
נגישות היא חשובה! כל התמנות חייבות להכיל :alt:
.
.. image:: images/my-document/my-image.png
:alt: An example image
תמונות וקטוריות
קבצי SVG נתמכים באמצעות הרחבת svg2pdfconverter
של Sphinx.
השתמשו בהם כמו בכל תמונה אחרת.
הערה
ודאו כי תמונות פקסלים בווקטור אינן מנפחות את גודל הקובץ כדי לחרוג ממגבלת 500KB.
.. image:: images/my-document/my-image.svg
:alt: Always add alt text here describing the image.
תרשימי Draw.io
תרשימי Draw.io (ידועים גם בשם diagrams.net) נתמכים באמצעות קבצי svg
עם מטא-דאטה .drawio
, המאפשר לקובץ ה-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
עם מטא-דאטה, עיינו במסמך הנחיות שמירת Draw.io.
אזהרה
הקפידו לא לערוך שום קובץ שנמצא בתיקיית diagrams
או מסתיים ב-.drawio.svg
, בכל תוכנית אחרת שאינה draw.io, אחרת אתם עלולים להסתכן בשבירת המטא-דאטה של הקובץ, מה שיהפוך אותו לבלתי ניתן לעריכה.
סיומות הקבצים
סיומות קבצים צריכות להשתמש בעיצוב קוד. לדוגמה, השתמשו ב:
``.png``
במקום:
.png
".png"
"``.png``"
תוכן עניינים
כל קטגוריה צריכה להכיל index.rst
. קובץ index זה צריך להכיל maxdepth
של 1
. תתי קטגוריות מקובלים, עם 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!
הערה חשובה!
רשימה זו אינה ממצה והמנהלים שומרים לעצמם את הזכות לבצע שינויים. שינויים יבואו לידי ביטוי במסמך זה.