دليل أسلوب توثيق TensorFlow

أفضل الممارسات

• التركيز على نية المستخدم والجمهور.
• استخدم الكلمات اليومية واجعل الجمل قصيرة.
• استخدم بناء الجملة، والصياغة، والأحرف الكبيرة بشكل متسق.
• استخدم العناوين والقوائم لتسهيل فحص مستنداتك.
• يعد دليل نمط محرّر مستندات Google Developer مفيدًا.

تخفيض السعر

مع بعض الاستثناءات، يستخدم TensorFlow بناء جملة Markdown المشابه لـ GitHub Flavoured 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
```

الروابط في تخفيض السعر والدفاتر

الروابط بين الملفات في المستودع

استخدم الروابط النسبية بين الملفات الموجودة في مستودع GitHub واحد. قم بتضمين امتداد الملف.

على سبيل المثال، هذا الملف الذي تقرأه موجود في مستودع https://github.com/tensorflow/docs . لذلك، يمكنه استخدام المسارات النسبية للربط بملفات أخرى في نفس المستودع مثل هذا:

• [Basics](../../guide/basics.ipynb) تنتج الأساسيات .

هذا هو الأسلوب المفضل لأن الروابط الموجودة على 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) لكل مشروع باستخدام واجهة برمجة تطبيقات Python المنشورة على Tensorflow.org . يمكنك بسهولة الارتباط بمشاريع فرعية متعددة من ملف واحد عن طريق تغليف أسماء واجهة برمجة التطبيقات (API) بعلامات اختيار خلفية. على سبيل المثال:

• ينتج عن `tf.metrics` و` `tf_agents.metrics` `text.metrics` : tf.metrics و tf_agents.metrics و text.metrics .

بالنسبة للرموز ذات الأسماء المستعارة المتعددة للمسارات، هناك تفضيل بسيط للمسار الذي يطابق صفحة API على Tensorflow.org . سيتم إعادة توجيه جميع الأسماء المستعارة إلى الصفحة الصحيحة.

الرياضيات في تخفيض السعر

يمكنك استخدام MathJax ضمن TensorFlow عند تحرير ملفات Markdown، لكن لاحظ ما يلي:

• يتم عرض 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 أو أي برنامج مستندات آخر لإجراء تدقيق إملائي ونحوي أكثر قوة.
• استخدم صوتًا عاديًا وودودًا. اكتب وثائق TensorFlow مثل المحادثة، كما لو كنت تتحدث مع شخص آخر وجهًا لوجه. استخدم لهجة داعمة في المقال.

• تجنب إخلاء المسؤولية والآراء والأحكام القيمة. كلمات مثل "بسهولة" و"فقط" و"بسيطة" مليئة بالافتراضات. قد يبدو شيء ما سهلاً بالنسبة لك، ولكنه صعب بالنسبة لشخص آخر. حاول تجنب هذه الأمور كلما أمكن ذلك.
• استخدم جملًا بسيطة ومباشرة بدون مصطلحات معقدة. الجمل المركبة، وسلاسل الجمل، والتعابير الخاصة بالموقع يمكن أن تجعل النص صعب الفهم والترجمة. إذا كان من الممكن تقسيم الجملة إلى قسمين، فمن المحتمل أن يكون ذلك ضروريًا. تجنب الفواصل المنقوطة. استخدم القوائم النقطية عند الاقتضاء.
• توفير السياق. لا تستخدم الاختصارات دون شرحها. لا تذكر المشاريع غير التابعة لـ TensorFlow دون الارتباط بها. اشرح سبب كتابة الكود بهذه الطريقة.

دليل الاستخدام

العمليات

في ملفات تخفيض السعر، استخدم # ⇒ بدلاً من علامة المساواة عندما تريد إظهار ما ترجعه العملية.

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

في دفاتر الملاحظات، اعرض النتيجة بدلاً من إضافة تعليق (إذا لم يتم تعيين التعبير الأخير في خلية دفتر الملاحظات إلى متغير، فسيتم عرضه تلقائياً.)

في المستندات المرجعية لواجهة برمجة التطبيقات، تفضل استخدام doctest لعرض النتائج.

الموترات

عندما تتحدث عن الموتر بشكل عام، لا تكتب كلمة موتر بحرف كبير. عندما تتحدث عن كائن محدد تم توفيره أو إرجاعه من عملية، فيجب عليك كتابة كلمة Tensor بالأحرف الكبيرة وإضافة علامات نقر خلفية حولها لأنك تتحدث عن كائن Tensor .

لا تستخدم كلمة Tensors (جمع) لوصف كائنات 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.