הנחיות סגנון
מסמך זה מכיל את ההנחיות הספציפיות של 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 פנימי
השתמשו ברווח אחד בין משפטים.
כותרות
הכותרות צריכות להיות במבנה הבא. הקו התחתון צריך להתאים למספר התווים של הכותרת עצמה.
=
לכותרות מסמכים. אל תשתמשו בזה יותר מפעם אחת לכל מאמר.-
עבור קטעי מסמך-
עבור תתי-קטע מסמך~
עבור תתי-תתי-קטע מסמךאם אתם צריכים להשתמש ברמות נמוכות יותר של מבנה, אתם עושים דברים לא נכונים.
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:
.. 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!
קישורים
עדיף לעצב קישורים כהיפר-קישורים אנונימיים. הדבר החשוב הוא הוספת שני הקווים התחתונים. במצב בו משתמשים רק בקו תחתון אחד, עלולות להיווצר בעיות בעת רינדור המסמך.
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.
קבצי תמונה
קבצי תמונה צריכים להיות מאוחסנים בתיקיית המסמכים, בתת-התיקייה של 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!
הערה חשובה!
רשימה זו אינה ממצה והמנהלים שומרים לעצמם את הזכות לבצע שינויים. שינויים יבואו לידי ביטוי במסמך זה.