راهنمای سبک مستندسازی TensorFlow

بهترین شیوه ها

• روی هدف کاربر و مخاطب تمرکز کنید.
• از کلمات روزمره استفاده کنید و جملات را کوتاه نگه دارید.
• از ساخت جمله، جمله بندی و حروف بزرگ استفاده کنید.
• از سرفصل‌ها و فهرست‌ها برای آسان‌تر کردن اسکن اسناد خود استفاده کنید.
• راهنمای سبک اسناد توسعه‌دهنده Google مفید است.

مارک داون

با چند استثنا، 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()`

بلوک های کد

از سه بکتیک برای باز و بسته کردن یک بلوک کد استفاده کنید. به صورت اختیاری، زبان برنامه نویسی را بعد از اولین گروه بکتیک مشخص کنید، به عنوان مثال:

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

پیوندها در Markdown و نوت بوک ها

پیوند بین فایل ها در یک مخزن

از پیوندهای نسبی بین فایل‌ها در یک مخزن GitHub استفاده کنید. پسوند فایل را وارد کنید.

به عنوان مثال، این فایلی که می خوانید از مخزن https://github.com/tensorflow/docs است. بنابراین، می‌تواند از مسیرهای نسبی برای پیوند به فایل‌های دیگر در همان مخزن مانند زیر استفاده کند:

• [Basics](../../guide/basics.ipynb) Basics را تولید می کند.

این رویکرد ترجیحی است زیرا به این ترتیب پیوندهای موجود در tensorflow.org ، GitHub و Colab همگی کار می کنند. همچنین، خواننده زمانی که روی یک لینک کلیک می کند، در همان سایت می ماند.

لینک های خارجی

برای پیوند به فایل‌هایی که در مخزن فعلی نیستند، از پیوندهای Markdown استاندارد با URI کامل استفاده کنید. اگر URI tensorflow.org در دسترس است، ترجیح دهید به آن پیوند دهید.

برای پیوند به کد منبع، از پیوندی استفاده کنید که با 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 یک نماد، مسیر نماد را در بکتیک ها قرار دهید:

• `tf.data.Dataset` tf.data.Dataset تولید می کند

مسیرهای کامل به جز مسیرهای طولانی کمی ترجیح داده می شوند. مسیرها را می توان با حذف اجزای مسیر پیشرو به اختصار مشخص کرد. مسیرهای جزئی به پیوند تبدیل می شوند اگر:

• حداقل یکی وجود دارد . در مسیر، و
• مسیر جزئی در پروژه منحصر به فرد است.

مسیرهای API برای هر پروژه با یک API پایتون منتشر شده در tensorflow.org پیوند داده شده است. شما به راحتی می توانید با قرار دادن نام های API با بکتیک به چندین زیر پروژه از یک فایل پیوند دهید. به عنوان مثال:

• `tf.metrics` ، `tf_agents.metrics` ، `text.metrics` تولید می‌کند: tf.metrics ، tf_agents.metrics ، text.metrics .

برای نمادهایی با نام مستعار مسیرهای متعدد، ترجیح کمی برای مسیری وجود دارد که با صفحه API در tensorflow.org مطابقت دارد. همه نام های مستعار به صفحه صحیح هدایت می شوند.

ریاضی در Markdown

هنگام ویرایش فایل‌های Markdown می‌توانید از MathJax در TensorFlow استفاده کنید، اما به نکات زیر توجه کنید:

• 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 را بدون پیوند به آنها ذکر نکنید. توضیح دهید که چرا کد به شکلی که هست نوشته شده است.

راهنمای استفاده

عملیات

در فایل‌های نشانه‌گذاری، وقتی می‌خواهید نشان دهید که یک op چه چیزی را برمی‌گرداند، به جای علامت مساوی از # ⇒ استفاده کنید.

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

در نوت‌بوک‌ها، به‌جای افزودن نظر، نتیجه را نمایش دهید (اگر آخرین عبارت در سلول نوت‌بوک به متغیری اختصاص داده نشود، به‌طور خودکار نمایش داده می‌شود.)

در API اسناد مرجع ترجیح می دهند از doctest برای نمایش نتایج استفاده کنند.

تانسورها

وقتی به طور کلی در مورد یک تانسور صحبت می کنید، کلمه تانسور را با حروف بزرگ ننویسید. وقتی در مورد شی خاصی صحبت می کنید که به یک op ارائه شده یا از آن برگردانده شده است، باید کلمه Tensor را با حروف بزرگ بنویسید و بکتیک هایی را در اطراف آن اضافه کنید زیرا در مورد یک شی Tensor صحبت می کنید.

از کلمه Tensor (جمع) برای توصیف چندین شی 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 است.