با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
رشته های مستند قابل آزمایش
TensorFlow از DocTest برای آزمایش تکه‌های کد در رشته‌های اسناد پایتون استفاده می‌کند. قطعه باید کد پایتون قابل اجرا باشد. برای فعال کردن تست، خط را با >>> (سه براکت زاویه چپ) پیش‌بند کنید. به عنوان مثال، در اینجا گزیده ای از تابع tf.concat در فایل منبع array_ops.py آمده است:
برای ارزیابی کیفیت اسناد مرجع، به بخش مثال توصیه 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 قابل مشاهده نیست.
مقادیر ممیز شناور : آزمون Doctest TensorFlow مقادیر شناور را از رشته‌های نتیجه استخراج می‌کند و با استفاده از np.allclose با تلورانس‌های معقول مقایسه می‌کند ( atol=1e-6 ، rtol=1e-6 ). به این ترتیب نویسندگان نیازی به نگرانی در مورد رشته های اسنادی بیش از حد دقیق که باعث خرابی به دلیل مسائل عددی می شوند، نخواهند بود. به سادگی مقدار مورد انتظار را بچسبانید.
خروجی غیر قطعی : از بیضی ( ... ) برای قسمت های نامشخص استفاده کنید و DocTest آن رشته فرعی را نادیده می گیرد.
اگر روی یک پروژه خارجی یا روی APIهای TensorFlow که در یک پروژه خارجی قرار دارند کار می‌کنید، این دستورالعمل‌ها کار نمی‌کنند مگر اینکه آن پروژه دارای کپی محلی خود از tf_doctest باشد و شما از آن نسخه به جای TensorFlow استفاده کنید.
دو راه برای آزمایش کد موجود در docstring به صورت محلی وجود دارد:
اگر فقط رشته مستند یک کلاس/تابع/روش را تغییر می‌دهید، می‌توانید با عبور مسیر آن فایل به tf_doctest.py آن را آزمایش کنید. به عنوان مثال:
pythontf_doctest.py--file=<file_path>
این آن را با استفاده از نسخه نصب شده TensorFlow اجرا می کند. برای اطمینان از اجرای همان کدی که در حال آزمایش آن هستید:
از نصب پیپ tf-nightly به روز pip install -U tf-nightly استفاده کنید
درخواست pull خود را بر روی یک کشش اخیر از شاخه اصلی TensorFlow تنظیم کنید.
اگر در حال تغییر کد و رشته مستند یک کلاس/تابع/روش هستید، باید TensorFlow را از منبع بسازید . پس از تنظیم برای ساخت از منبع، می توانید تست ها را اجرا کنید:
تاریخ آخرین بهروزرسانی 2025-01-14 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-01-14 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Contribute to the TensorFlow API documentation\n\n\u003cbr /\u003e\n\nTestable docstrings\n-------------------\n\nTensorFlow uses [DocTest](https://docs.python.org/3/library/doctest.html) to\ntest code snippets in Python docstrings. The snippet must be executable Python\ncode. To enable testing, prepend the line with `\u003e\u003e\u003e` (three left-angle\nbrackets). For example, here's a excerpt from the [`tf.concat`](https://www.tensorflow.org/api_docs/python/tf/concat) function in the\n[array_ops.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/ops/array_ops.py)\nsource file: \n\n def concat(values, axis, name=\"concat\"):\n \"\"\"Concatenates tensors along one dimension.\n ...\n\n \u003e\u003e\u003e t1 = [[1, 2, 3], [4, 5, 6]]\n \u003e\u003e\u003e t2 = [[7, 8, 9], [10, 11, 12]]\n \u003e\u003e\u003e concat([t1, t2], 0)\n \u003ctf.Tensor: shape=(4, 3), dtype=int32, numpy=\n array([[ 1, 2, 3],\n [ 4, 5, 6],\n [ 7, 8, 9],\n [10, 11, 12]], dtype=int32)\u003e\n\n \u003c... more description or code snippets ...\u003e\n\n Args:\n values: A list of `tf.Tensor` objects or a single `tf.Tensor`.\n axis: 0-D `int32` `Tensor`. Dimension along which to concatenate. Must be\n in the range `[-rank(values), rank(values))`. As in Python, indexing for\n axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers\n to `axis`-th dimension. And negative axis refers to `axis +\n rank(values)`-th dimension.\n name: A name for the operation (optional).\n\n Returns:\n A `tf.Tensor` resulting from concatenation of the input tensors.\n \"\"\"\n\n \u003ccode here\u003e\n\n| **Note:** TensorFlow DocTest uses TensorFlow 2 and Python 3.\n\nTo assess reference documentation quality, see the example section of the\n[TensorFlow 2 API Docs advice](https://docs.google.com/document/d/1e20k9CuaZ_-hp25-sSd8E8qldxKPKQR-SkwojYr_r-U/preview).\n(Be aware that the Task Tracker on this sheet is no longer in use.)\n\n### Make the code testable with DocTest\n\nCurrently, many docstrings use backticks (\\`\\`\\`) to identify code. To make the\ncode testable with DocTest:\n\n- Remove the backticks (\\`\\`\\`) and use the left-brackets (\\\u003e\\\u003e\\\u003e) in front of each line. Use (...) in front of continued lines.\n- Add a newline to separate DocTest snippets from Markdown text to render properly on tensorflow.org.\n\n### Customizations\n\nTensorFlow uses a few customizations to the builtin doctest logic:\n\n- It does not compare float values as text: Float values are extracted from the text and compared using `allclose` with *liberal `atol` and `rtol`\n tolerences* . This allows :\n - Clearer docs - Authors don't need to include all decimal places.\n - More robust tests - Numerical changes in the underlying implementation should never cause a doctest to fail.\n- It only checks the output if the author includes output for a line. This allows for clearer docs because authors usually don't need to capture irrelevant intermediate values to prevent them from being printed.\n\n### Docstring considerations\n\n- *Overall* : The goal of doctest is to provide documentation, and confirm that the documentation works. This is different from unit-testing. So:\n - Keep examples simple.\n - Avoid long or complicated outputs.\n - Use round numbers if possible.\n- *Output format* : The output of the snippet needs to be directly beneath the code that's generating the output. Also, the output in the docstring has to be exactly equal to what the output would be after the code is executed. See the above example. Also, check out [this part](https://docs.python.org/3/library/doctest.html#warnings) in the DocTest documentation. If the output exceeds the 80 line limit, you can put the extra output on the new line and DocTest will recognize it. For example, see multi-line blocks below.\n- *Globals* : The ```tf```, `np` and `os` modules are always available in TensorFlow's DocTest.\n- *Use symbols* : In DocTest you can directly access symbols defined in the\n same file. To use a symbol that's not defined in the current file, please\n use TensorFlow's public API `tf.xxx` instead of `xxx`. As you can see in the\n example below, ```random.normal``` is accessed via\n ```tf.random.normal```. This is because\n ```random.normal``` is not visible in `NewLayer`.\n\n def NewLayer():\n \"\"\"This layer does cool stuff.\n\n Example usage:\n\n \u003e\u003e\u003e x = tf.random.normal((1, 28, 28, 3))\n \u003e\u003e\u003e new_layer = NewLayer(x)\n \u003e\u003e\u003e new_layer\n \u003ctf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...\u003e\n \"\"\"\n\n- *Floating point values* : The TensorFlow doctest extracts float values from\n the result strings, and compares using `np.allclose` with reasonable\n tolerances (`atol=1e-6`, `rtol=1e-6`). This way authors do not need to worry\n about overly precise docstrings causing failures due to numerical issues.\n Simply paste in the expected value.\n\n- *Non-deterministic output* : Use ellipsis(`...`) for the uncertain parts and\n DocTest will ignore that substring.\n\n x = tf.random.normal((1,))\n print(x)\n \u003ctf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)\u003e\n \n- *Multi-line blocks*: DocTest is strict about the difference between a single\n and a multi-line statement. Note the usage of (...) below:\n\n if x \u003e 0:\n print(\"X is positive\")\n model.compile(\n loss=\"mse\",\n optimizer=\"adam\")\n \n- *Exceptions* : Exception details are ignored except the Exception that's\n raised. See\n [this](https://docs.python.org/3/library/doctest.html#doctest.IGNORE_EXCEPTION_DETAIL)\n for more details.\n\n np_var = np.array([1, 2])\n tf.keras.backend.is_keras_tensor(np_var)\n Traceback (most recent call last):\n\n ValueError: Unexpectedly found an instance of type `\u003cclass 'numpy.ndarray'\u003e`.\n \n### Use a project-local copy of tf-doctest.\n\n| **Note:** The tf-doctest utility is only setup to test source files within the `tensorflow` repository. If the files you are editing are in TensorFlow you can skip to the next section. Otherwise keep reading this section.\n\nSome API's in TensorFlow come from an external project:\n\n- `tf.estimator` (from [tensorflow_estimator](https://github.com/tensorflow/estimator))\n- [`tf.summary`](https://www.tensorflow.org/api_docs/python/tf/summary) [tensorboard](https://github.com/tensorflow/tensorboard))\n- [`tf.keras.preprocessing`](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing) (from [keras-preprocessing](https://github.com/keras-team/keras-preprocessing))\n\nIf you're working on an external project, or on TensorFlow APIs that are housed\nin an external project, these instructions won't work unless that project has\nits own local copy of `tf_doctest`, and you use that copy instead of\nTensorFlow's.\n\nFor example:\n[tf_estimator_doctest.py](https://github.com/tensorflow/estimator/python/estimator/tf_estimator_doctest.py).\n\n### Test on your local machine\n\nThere are two ways to test the code in the docstring locally:\n\n- If you are only changing the docstring of a class/function/method, then you\n can test it by passing that file's path to\n [tf_doctest.py](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docs/tf_doctest.py).\n For example:\n\n python tf_doctest.py --file=\u003cfile_path\u003e\n\n This will run it using your installed version of TensorFlow. To be sure\n you're running the same code that you're testing:\n - Use an up to date [tf-nightly](https://pypi.org/project/tf-nightly/) `pip install -U tf-nightly`\n - Rebase your pull request onto a recent pull from [TensorFlow's](https://github.com/tensorflow/tensorflow) master branch.\n- If you are changing the code and the docstring of a class/function/method,\n then you will need to\n [build TensorFlow from source](../../install/source). Once you are setup\n to build from source, you can run the tests:\n\n bazel run //tensorflow/tools/docs:tf_doctest\n\n or \n\n bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops\n\n The `--module` is relative to `tensorflow.python`."]]
