در اسناد TensorFlow API مشارکت کنید

رشته های مستند قابل آزمایش

TensorFlow از DocTest برای آزمایش تکه‌های کد در رشته‌های اسناد پایتون استفاده می‌کند. قطعه باید کد پایتون قابل اجرا باشد. برای فعال کردن تست، خط را با >>> (سه براکت زاویه چپ) پیش‌بند کنید. به عنوان مثال، در اینجا گزیده ای از تابع 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 قابل آزمایش کنید

در حال حاضر، بسیاری از رشته‌های اسناد از بکتیک (``) برای شناسایی کد استفاده می‌کنند. برای تست شدن کد با DocTest:

  • بکتیک ها (```) را بردارید و از براکت های چپ (>>>) در جلوی هر خط استفاده کنید. از (...) در جلوی خطوط ادامه دار استفاده کنید.
  • یک خط جدید اضافه کنید تا قطعات DocTest را از متن Markdown جدا کنید تا به درستی در tensorflow.org رندر شوند.

سفارشی سازی ها

TensorFlow از چند سفارشی سازی برای منطق doctest داخلی استفاده می کند:

  • مقادیر شناور را به عنوان متن مقایسه نمی‌کند: مقادیر شناور از متن استخراج می‌شوند و با استفاده از allclose با تحمل‌های لیبرال atol و rtol مقایسه می‌شوند. این اجازه می دهد:
    • اسناد واضح تر - نویسندگان نیازی به گنجاندن تمام ارقام اعشاری ندارند.
    • تست‌های قوی‌تر - تغییرات عددی در پیاده‌سازی اساسی هرگز نباید باعث شکست یک doctest شود.
  • تنها در صورتی خروجی را بررسی می کند که نویسنده خروجی برای یک خط داشته باشد. این اجازه می دهد تا اسناد واضح تری داشته باشید زیرا نویسندگان معمولاً نیازی به گرفتن مقادیر میانی نامربوط برای جلوگیری از چاپ آنها ندارند.

ملاحظات مستندسازی

  • به طور کلی : هدف doctest ارائه مستندات و تأیید کارکرد اسناد است. این با تست واحد متفاوت است. بنابراین:
    • مثال ها را ساده نگه دارید.
    • از خروجی های طولانی یا پیچیده خودداری کنید.
    • در صورت امکان از اعداد گرد استفاده کنید.
  • فرمت خروجی : خروجی قطعه باید مستقیماً زیر کدی باشد که خروجی را تولید می کند. همچنین، خروجی در رشته docstring باید دقیقاً برابر با خروجی پس از اجرای کد باشد. مثال بالا را ببینید. همچنین، این بخش را در مستندات DocTest بررسی کنید. اگر خروجی از حد 80 خط بیشتر شود، می توانید خروجی اضافی را در خط جدید قرار دهید و DocTest آن را تشخیص خواهد داد. به عنوان مثال، بلوک های چند خطی را در زیر ببینید.
  • Globals : ماژول‌های `tf` ، np و os همیشه در DocTest TensorFlow در دسترس هستند.

  • استفاده از نمادها : در DocTest می توانید مستقیماً به نمادهای تعریف شده در همان فایل دسترسی داشته باشید. برای استفاده از نمادی که در فایل فعلی تعریف نشده است، لطفاً به جای xxx از API عمومی TensorFlow tf.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=...>
  """

  • مقادیر ممیز شناور : آزمون Doctest TensorFlow مقادیر شناور را از رشته‌های نتیجه استخراج می‌کند و با استفاده از 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 از یک پروژه خارجی می آیند:

اگر روی یک پروژه خارجی یا روی APIهای TensorFlow که در یک پروژه خارجی قرار دارند کار می‌کنید، این دستورالعمل‌ها کار نمی‌کنند مگر اینکه آن پروژه دارای کپی محلی خود از tf_doctest باشد و شما از آن نسخه به جای TensorFlow استفاده کنید.

به عنوان مثال: tf_estimator_doctest.py .

روی دستگاه محلی خود تست کنید

دو راه برای آزمایش کد موجود در docstring به صورت محلی وجود دارد:

  • اگر فقط رشته مستند یک کلاس/تابع/روش را تغییر می‌دهید، می‌توانید با عبور مسیر آن فایل به tf_doctest.py آن را آزمایش کنید. به عنوان مثال:

    python tf_doctest.py --file=<file_path>

    این آن را با استفاده از نسخه نصب شده TensorFlow اجرا می کند. برای اطمینان از اجرای همان کدی که در حال آزمایش آن هستید:

    • از نصب پیپ tf-nightly به روز pip install -U tf-nightly استفاده کنید
    • درخواست pull خود را بر روی یک کشش اخیر از شاخه اصلی TensorFlow تنظیم کنید.

  • اگر در حال تغییر کد و رشته مستند یک کلاس/تابع/روش هستید، باید TensorFlow را از منبع بسازید . پس از تنظیم برای ساخت از منبع، می توانید تست ها را اجرا کنید:

    bazel run //tensorflow/tools/docs:tf_doctest

    یا

    bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops

    ماژول --module نسبت به tensorflow.python است.