מדריך סגנון תיעוד של TensorFlow

שיטות עבודה מומלצות

  • התמקד בכוונת המשתמש ובקהל.
  • השתמש במילים יומיומיות ושמור משפטים קצרים.
  • השתמש בבניית משפטים עקביים, בניסוח ובאותיות רישיות.
  • השתמש בכותרות ורשימות כדי להקל על הסריקה של המסמכים שלך.
  • מדריך הסגנונות של Google Developer Docs מועיל.

Markdown

למעט כמה חריגים, TensorFlow משתמש בתחביר Markdown הדומה ל- GitHub Flavored Markdown (GFM). סעיף זה מסביר את ההבדלים בין תחביר GFM Markdown לבין Markdown המשמש לתיעוד TensorFlow.

כתוב על קוד

אזכורים מוטבעים של קוד

שים `backticks` סביב הסמלים הבאים בעת שימוש בטקסט:

  • שמות ארגומנטים: `input` , `x` , `tensor`
  • שמות טנסור שהוחזרו: `output` , `idx` , `out`
  • סוגי נתונים: `int32` , `float` , `uint8`
  • שמות אופ אחרים הפניות בטקסט: `list_diff()` , `shuffle()`
  • שמות כיתות: `tf.Tensor` , `Strategy`
  • שם הקובץ: `image_ops.py` , `/path_to_dir/file_name`
  • ביטויים או תנאים מתמטיים: `-1-input.dims() <= dim <= input.dims()`

קוביות קוד

השתמש בשלושה סימנים לאחור כדי לפתוח ולסגור בלוק קוד. אופציונלי, ציין את שפת התכנות לאחר קבוצת ה-backtick הראשונה, לדוגמה:


```python
# some python code here
```

השתמש בקישורים יחסיים בין קבצים במאגר GitHub יחיד. כלול את סיומת הקובץ.

לדוגמה, הקובץ הזה שאתה קורא הוא מהמאגר https://github.com/tensorflow/docs . לכן, הוא יכול להשתמש בנתיבים יחסיים כדי לקשר לקבצים אחרים באותו מאגר כך:

  • [Basics](../../guide/basics.ipynb) מייצר Basics .

זו הגישה המועדפת מכיוון שככה הקישורים ב- tensorflow.org , GitHub ו- Colab עובדים כולם. כמו כן, הקורא נשאר באותו אתר כשהוא לוחץ על קישור.

עבור קישורים לקבצים שאינם במאגר הנוכחי, השתמש בקישורי Markdown סטנדרטיים עם URI המלא. העדיפו לקשר אל tensorflow.org URI אם הוא זמין.

כדי לקשר לקוד המקור, השתמש בקישור שמתחיל ב- https://www.github.com/tensorflow/tensorflow/blob/master/ , ואחריו שם הקובץ שמתחיל בשורש GitHub.

בעת קישור מחוץ ל- tensorflow.org , כלול `` בקישור Markdown כך שהסמל "קישור חיצוני" יוצג.

  • [GitHub](https://github.com/tensorflow/docs) מייצר את GitHub

אל תכלול פרמטרים של שאילתת URI בקישור:

  • השתמש ב: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • לא: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

תמונות

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

ככלל, אסור לבצע צ'ק אין תמונות, ובמקום זאת להוסיף את צוות TensorFlow-Docs ליחסי הציבור שלך, ולבקש מהם לארח את התמונות באתר tensorflow.org . זה עוזר לשמור על גודל המאגר שלך.

אם אתה אכן שולח תמונות למאגר שלך, שים לב שמערכות מסוימות אינן מטפלות בנתיבים יחסיים לתמונות. העדיפו להשתמש בכתובת URL מלאה המפנה למיקום הסופי של התמונה ב- tensorflow.org .

קישורי API מומרים כאשר האתר מתפרסם. כדי לקשר לדף ההתייחסות של ה-API של סמל, הוסף את נתיב הסמל בתווים אחוריים:

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

  • יש לפחות אחד . בנתיב, ו
  • הדרך החלקית היא ייחודית בתוך הפרויקט.

נתיבי API מקושרים לכל פרויקט עם Python API שפורסם באתר tensorflow.org . אתה יכול לקשר בקלות למספר תת-פרויקטים מקובץ בודד על ידי גלישת שמות ה-API עם סימנים לאחור. לְדוּגמָה:

עבור סמלים עם כינויים מרובים של נתיב יש העדפה קלה לנתיב התואם לדף ה-API ב- tensorflow.org . כל הכינויים יופנו לדף הנכון.

מתמטיקה ב-Markdown

אתה יכול להשתמש ב- MathJax בתוך TensorFlow בעת עריכת קובצי Markdown, אך שים לב לדברים הבאים:

  • MathJax מעבד כראוי ב- tensorflow.org .
  • MathJax אינו מעבד כראוי ב- GitHub.
  • סימון זה יכול להרתיע מפתחים לא מוכרים.
  • לצורך עקביות tensorflow.org פועל לפי אותם כללים כמו Jupyter/Colab.

השתמש ב $$ סביב גוש של MathJax: 

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

עטוף ביטויי MathJax מוטבעים עם $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

זוהי דוגמה לביטוי MathJax מוטבע: \( 2 \times 2 = 4 \)

\\( ... \\) מפרידים עובדים גם עבור מתמטיקה מוטבעת, אבל הטופס $ לפעמים קריא יותר.

סגנון פרוזה

אם אתה מתכוון לכתוב או לערוך חלקים נכבדים מהתיעוד הנרטיבי, קרא את מדריך התיעוד של Google למפתחים .

עקרונות של סגנון טוב

  • בדוק את האיות והדקדוק בתרומות שלך. רוב העורכים כוללים בודק איות או שיש להם תוסף זמין לבדיקת איות. אתה יכול גם להדביק את הטקסט שלך ב-Google Doc או בתוכנת מסמכים אחרת לבדיקת איות ודקדוק חזקה יותר.
  • השתמש בקול סתמי וידידותי. כתוב תיעוד של TensorFlow כמו שיחה - כאילו אתה מדבר עם אדם אחר אחד על אחד. השתמש בטון תומך במאמר.
  • הימנע מהסתייגות, דעות ושיפוטים ערכיים. מילים כמו "בקלות", "סתם" ו"פשוט" עמוסות בהנחות יסוד. משהו אולי נראה לך קל, אבל קשה עבור אדם אחר. נסו להימנע מאלה בכל הזדמנות אפשרית.
  • השתמש במשפטים פשוטים וענייניים ללא ז'רגון מסובך. משפטים מורכבים, שרשרות של סעיפים וניבים ספציפיים למיקום יכולים להפוך טקסט לקשה להבנה ולתרגום. אם אפשר לפצל משפט לשניים, כנראה שצריך. הימנע מנקודות פסיק. השתמש ברשימות תבליטים כאשר מתאים.
  • ספק הקשר. אל תשתמש בקיצורים מבלי להסביר אותם. אל תזכיר פרויקטים שאינם של TensorFlow מבלי לקשר אליהם. הסבר מדוע הקוד כתוב כמו שהוא.

מדריך שימוש

אופס

בקבצי סימון, השתמשו ב- # ⇒ במקום בסימן שוויון בודד כאשר ברצונכם להראות מה מחזיר אופ.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

במחברות, הצג את התוצאה במקום להוסיף הערה (אם הביטוי האחרון בתא מחברת אינו מוקצה למשתנה, הוא יוצג אוטומטית).

בהפניה ל-API, מסמכים מעדיפים להשתמש ב- doctest כדי להציג תוצאות.

טנסורים

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

אל תשתמש במילה Tensors (רבים) כדי לתאר מספר אובייקטים Tensor אלא אם כן אתה באמת מדבר על אובייקט Tensors . במקום זאת, אמור "רשימה (או אוסף) של חפצי Tensor ".

השתמש במילה צורה כדי לפרט את הצירים של טנזור, והצג את הצורה בסוגריים מרובעים עם סימנים לאחור. לְדוּגמָה:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

כמו לעיל, העדיפו "ציר" או "אינדקס" על פני "מימד" כאשר מדברים על האלמנטים של צורת Tensor . אחרת קל לבלבל בין "מימד" לממד של מרחב וקטורי. ל"וקטור תלת מימדי" יש ציר בודד באורך 3.