הנחיות סגנון

מסמך זה מכיל את ההנחיות הספציפיות של RST/Sphinx לפרויקט frc-docs. להנחיות הקשורות לפרויקטי קוד WPILib השונים, ראו את ה-GitHub של WPILib

שמות הקבצים

השתמשו רק באותיות קטנות באנגלית, במספרים, ובסימן - (מינוס).

למסמכים בעלי שם תוכנה/חומרה זהה, הוסיפו ”Hardware“ או ”Software“ בסוף שם הקובץ. לדוגמא, ultrasonics-hardware.rst.

תנו לקבצים את הסיומת .rst.

הערה

במידה ואתם נתקלדים בבעיות בעריכת קבצים עם הסיומת .rst, עורך הטקסט המומלץ הוא Notepad++. אנא וודא כי אתם מחליפים טאבים ברווחים ומשתמשים בהזחה של 3 רווחים.

התייחסות לדפים

התייחסויות לדפים ייווצרו אוטומטית בהתבסס על שם קובץ הדף וכותרת הקטע.

לדוגמא, בהתחשב בקובץ הבא contributing.rst ובקטע שנקרא Page References, ניתן להתייחס לכך על ידי: :ref:`contributing:Page References`.

הערה

Please note that document structure is preserved in references, with the root being the location of the conf.py file. To access documents in sub-folders, simply prepend the folder path before the filename. IE, :ref:`docs/software/hardware-apis/sensors/ultrasonics-sensors:Ultrasonics - Sensors`

טקסט

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

השתמשו בהתאמות האותיות הגדולות והקטנות באנגלית הבאות למונחים אלו:

  • 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.

שורות ריקות

צריכה להיות שורה 1 ריקה המפרידה בין בלוקי טקסט בסיסיים לבין כותרות קטע. צריכה להיות שורה 1 ריקה המפרידה בין בלוקי טקסט לבין הוראות תוכן.

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/v2022.4.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/v2022.4.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.

אזהרות

אזהרות (רשימה כאן) צריכות להכיל את הטקסט באותה שורה כמו ההמלצה עצמה. ישנם יוצאים מן הכלל, עם זאת, כאשר ישנם חלקים מרובים של תוכן בתוך ההנחיה. בדרך כלל לא מומלץ להשתמש בחלקים מסוימים של תוכן בתוך אזהרה.

השתמשו ב:

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

קבצי תמונה

קבצי תמונה צריכים להיות מאוחסנים בתיקיית המסמכים, בתת-התיקייה של 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 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!

הערה חשובה!

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