דף זה תורגם על ידי Cloud Translation API.

תרום לתיעוד TensorFlow API

מחרוזות מסמכים הניתנות לבדיקה

TensorFlow משתמש ב- DocTest כדי לבדוק קטעי קוד ב-Python docstrings. הקטע חייב להיות קוד Python בר הפעלה. כדי לאפשר בדיקה, הכנס לפני השורה >>> (שלוש סוגריים של זווית שמאל). לדוגמה, הנה קטע מהפונקציה tf.concat בקובץ המקור array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

כדי להעריך את איכות תיעוד ההפניה, עיין בסעיף הדוגמה של העצה של TensorFlow 2 API Docs . (שים לב ש-Task Tracker בגיליון זה אינו בשימוש עוד.)

הפוך את הקוד לניתן לבדיקה עם DocTest

נכון לעכשיו, מחרוזות docstrings רבות משתמשות ב-backticks (```) כדי לזהות קוד. כדי להפוך את הקוד לניתן לבדיקה עם DocTest:

הסר את הסימנים האחוריים (```) והשתמש בסוגריים השמאליים (>>>) לפני כל שורה. השתמש ב-(...) לפני המשך קווים.
הוסף שורה חדשה כדי להפריד בין קטעי DocTest מטקסט Markdown לעיבוד כראוי ב-tensorflow.org.

התאמות אישיות

TensorFlow משתמש במספר התאמות אישיות ללוגיקה המובנית של doctest:

זה לא משווה ערכי צף כטקסט: ערכי צף מופקים מהטקסט ומשווים באמצעות allclose עם סובלנות atol ו- rtol ליברליות . זה מאפשר:
- מסמכים ברורים יותר - מחברים אינם צריכים לכלול את כל המקומות העשרוניים.
- בדיקות חזקות יותר - שינויים מספריים ביישום הבסיסי לעולם לא אמורים לגרום לבדיקת doctest להיכשל.
זה בודק את הפלט רק אם המחבר כולל פלט עבור שורה. זה מאפשר מסמכים ברורים יותר מכיוון שמחברים בדרך כלל לא צריכים ללכוד ערכי ביניים לא רלוונטיים כדי למנוע מהם להיות מודפסים.

שיקולי דוקטורט

בסך הכל : המטרה של doctest היא לספק תיעוד, ולאשר שהתיעוד עובד. זה שונה מבדיקת יחידות. כָּך:
- שמור על דוגמאות פשוטות.
- הימנע מיציאות ארוכות או מסובכות.
- השתמש במספרים עגולים אם אפשר.
פורמט פלט : הפלט של קטע הקוד צריך להיות ישירות מתחת לקוד שיוצר את הפלט. כמו כן, הפלט ב-docstring חייב להיות שווה בדיוק למה שהפלט יהיה לאחר ביצוע הקוד. ראה את הדוגמה לעיל. כמו כן, בדוק את החלק הזה בתיעוד DocTest. אם הפלט חורג ממגבלת 80 השורות, אתה יכול לשים את הפלט הנוסף על הקו החדש ו-DocTest יזהה אותו. לדוגמה, ראה בלוקים מרובי שורות למטה.
גלובלים : המודולים `tf` , np ו- os זמינים תמיד ב-DocTest של TensorFlow.
השתמש בסמלים : ב-DocTest אתה יכול לגשת ישירות לסמלים המוגדרים באותו קובץ. כדי להשתמש בסמל שאינו מוגדר בקובץ הנוכחי, אנא השתמש ב-API הציבורי של TensorFlow tf.xxx במקום xxx . כפי שניתן לראות בדוגמה למטה, הגישה אל `random.normal` מתבצעת דרך `tf.random.normal` . הסיבה לכך היא ש `random.normal` אינו גלוי ב- NewLayer .
```
def NewLayer():
  """This layer does cool stuff.

  Example usage:

  >>> x = tf.random.normal((1, 28, 28, 3))
  >>> new_layer = NewLayer(x)
  >>> new_layer
  <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
  """
```
ערכי נקודה צפה : ה-TensorFlow doctest מחלץ ערכי ציפה ממחרוזות התוצאה, ומשווה שימוש ב- np.allclose עם סובלנות סבירות ( atol=1e-6 , rtol=1e-6 ). בדרך זו המחברים אינם צריכים לדאוג ששרשרת מסמכים מדויקת מדי הגורמת לכשלים עקב בעיות מספריות. כל שעליך לעשות הוא להדביק את הערך הצפוי.
פלט לא דטרמיניסטי : השתמש באליפסיס ( ... ) עבור החלקים הלא ודאיים ו-DocTest יתעלם מאותה מחרוזת משנה.
```
x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>
    
```
בלוקים מרובי שורות : DocTest מקפיד על ההבדל בין הצהרה בודדת לרב שורות. שימו לב לשימוש ב-(...) למטה:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

חריגים : מתעלמים מפרטי חריגים מלבד החריג שהועלה. ראה זאת לפרטים נוספים.

np_var = np.array([1, 2])
tf.keras.backend.is_keras_tensor(np_var)
    Traceback (most recent call last):

    ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.

השתמש בעותק מקומי של tf-doctest.

כמה ממשקי API ב-TensorFlow מגיעים מפרויקט חיצוני:

tf.estimator (מ- tensorflow_estimator )
tf.summary tensorboard )
tf.keras.preprocessing (מ- keras-preprocessing )

אם אתה עובד על פרויקט חיצוני, או על ממשקי API של TensorFlow שממוקמים בפרויקט חיצוני, הוראות אלו לא יעבדו אלא אם לפרוייקט יש עותק מקומי משלו של tf_doctest , ואתה משתמש בעותק הזה במקום של TensorFlow.

לדוגמה: tf_estimator_doctest.py .

בדוק במחשב המקומי שלך

ישנן שתי דרכים לבדוק את הקוד במחרוזת הדוק באופן מקומי:

אם אתה משנה רק את מחרוזת הדוק של מחלקה/פונקציה/שיטה, אז אתה יכול לבדוק אותה על ידי העברת הנתיב של הקובץ ל- tf_doctest.py . לְדוּגמָה:
```
python tf_doctest.py --file=<file_path>
```
זה יפעיל אותו באמצעות הגרסה המותקנת שלך של TensorFlow. כדי להיות בטוח שאתה מפעיל את אותו קוד שאתה בודק:
- השתמש בהתקנה מעודכנת של tf-nightly pip install -U tf-nightly
- בסיס מחדש את בקשת המשיכה שלך על משיכה אחרונה מהענף הראשי של TensorFlow .
אם אתה משנה את הקוד ואת המחרוזת של מחלקה/פונקציה/שיטה, תצטרך לבנות את TensorFlow ממקור . לאחר שתגדיר לבנות ממקור, תוכל להריץ את הבדיקות:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
אוֹ
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
--module הוא יחסית ל tensorflow.python .