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

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

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

نشانه‌گذاری

با چند استثنا، TensorFlow از یک سینتکس Markdown مشابه GitHub Flavored Markdown (GFM) استفاده می‌کند. این بخش تفاوت‌های بین سینتکس Markdown GFM و 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 و دفترچه‌های یادداشت

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

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

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

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

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

پیوندهای خارجی

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

برای لینک دادن به کد منبع، از لینکی که با https://www.github.com/tensorflow/tensorflow/blob/master/ شروع می‌شود و به دنبال آن نام فایل که از ریشه GitHub شروع می‌شود، استفاده کنید.

هنگام لینک دادن از tensorflow.org ، یک `` روی لینک Markdown قرار دهید تا نماد "لینک خارجی" نمایش داده شود.

• [GitHub](https://github.com/tensorflow/docs) گیت‌هاب را تولید می‌کند

پارامترهای کوئری URI را در لینک قرار ندهید:

• استفاده از: https://www.tensorflow.org/guide/data
• نه: https://www.tensorflow.org/guide/data?hl=en

تصاویر

توصیه‌ای که در بخش قبلی مطرح شد، برای لینک‌های صفحات بود. تصاویر به طور متفاوتی مدیریت می‌شوند.

به طور کلی، شما نباید تصاویر را بررسی کنید، و در عوض تیم TensorFlow-Docs را به PR خود اضافه کنید و از آنها بخواهید که تصاویر را در 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 Doc یا سایر نرم‌افزارهای سندسازی پیست کنید تا بررسی املا و دستور زبان دقیق‌تری انجام شود.
• از لحنی خودمانی و دوستانه استفاده کنید. مستندات TensorFlow را مانند یک مکالمه بنویسید - انگار که با شخص دیگری رو در رو صحبت می‌کنید. در مقاله از لحنی حمایتی استفاده کنید.

• از سلب مسئولیت، اظهار نظر و قضاوت‌های ارزشی خودداری کنید. کلماتی مانند «به راحتی»، «فقط» و «ساده» مملو از فرضیات هستند. ممکن است چیزی برای شما آسان به نظر برسد، اما برای شخص دیگری دشوار باشد. سعی کنید تا حد امکان از این موارد اجتناب کنید.
• از جملات ساده و مستقیم و بدون اصطلاحات پیچیده استفاده کنید. جملات مرکب، زنجیره‌ای از بندها و اصطلاحات خاص مکان می‌توانند درک و ترجمه متن را دشوار کنند. اگر جمله‌ای را بتوان به دو قسمت تقسیم کرد، احتمالاً باید این کار را انجام داد. از نقطه ویرگول اجتناب کنید. در صورت لزوم از فهرست‌های گلوله‌ای استفاده کنید.
• زمینه را فراهم کنید. از اختصارات بدون توضیح آنها استفاده نکنید. از پروژه‌های غیر TensorFlow بدون لینک دادن به آنها نام نبرید. توضیح دهید که چرا کد به این شکل نوشته شده است.

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

عملیات

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

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

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

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

تانسورها

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

از کلمه Tensors (جمع) برای توصیف چندین شیء Tensor استفاده نکنید، مگر اینکه واقعاً در مورد یک شیء Tensors صحبت می‌کنید. در عوض، بگویید «لیست (یا مجموعه‌ای) از اشیاء Tensor ».

از کلمه shape برای جزئیات محورهای یک تانسور استفاده کنید و شکل را داخل کروشه با علامت + نشان دهید. برای مثال:

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 «محور» یا «شاخص» را به «بعد» ترجیح دهید. در غیر این صورت، به راحتی می‌توان «بعد» را با بُعد یک فضای برداری اشتباه گرفت. یک «بردار سه‌بعدی» یک محور واحد با طول ۳ دارد.