הנחיות סגנון

מסמך זה מכיל את ההנחיות הספציפיות של 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 פנימי

השתמשו ברווח אחד בין משפטים.

כותרות

הכותרות צריכות להיות במבנה הבא. הקו התחתון צריך להתאים למספר התווים של הכותרת עצמה.

  1. = לכותרות מסמכים. אל תשתמשו בזה יותר מפעם אחת לכל מאמר.

  2. - עבור קטעי מסמך

  3. - עבור תתי-קטע מסמך

  4. ~ עבור תתי-תתי-קטע מסמך

  5. אם אתם צריכים להשתמש ברמות נמוכות יותר של מבנה, אתם עושים דברים לא נכונים.

Use title case for headings.

רשימות

לרשימות צריך להיות קו חדש בכל רמת הזחה. על רשימה הגבוהה ביותר צריכה להיות בהזחה 0, ורשימות המשנה הבאות צריכות להיות בהזחה החל מהתו הראשון של ההזחה הקודמת.

- Block one
- Block two
- Block three

  - Sub 1
  - Sub 2

- Block four

בלוקי קוד

יש לציין שפה לכל בלוקי הקוד.

  1. חריג: תוכן בו יש לשמור על עיצוב ואין לו שפה. במקום זאת השתמשו ב- 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:

.. group-tab:: Java

   .. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.2.1/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/ramsetecontroller/Robot.java
      :language: java
      :lines: 44-61
      :linenos:
      :lineno-start: 44

.. group-tab:: C++

   .. rli:: https://raw.githubusercontent.com/wpilibsuite/allwpilib/v2023.2.1/wpilibcExamples/src/main/cpp/examples/RamseteController/cpp/Robot.cpp
      :language: cpp
      :lines: 18-30
      :linenos:
      :lineno-start: 18

Note that group-tab rather than code-tab needs to be used. Also 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.

אזהרות

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!

תמונות

תמונות צריכות להיות עם שורה 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!

הערה חשובה!

רשימה זו אינה ממצה והמנהלים שומרים לעצמם את הזכות לבצע שינויים. שינויים יבואו לידי ביטוי במסמך זה.