Save the date! Google I/O returns May 18-20 Register now
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

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

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

تخفيض السعر

مع بعض الاستثناءات ، يستخدم TensorFlow صيغة Markdown مشابهة لـ GitHub Flavored Markdown (GFM). يشرح هذا القسم الاختلافات بين بناء جملة GFM Markdown و Markdown المستخدم لوثائق TensorFlow.

اكتب عن الكود

إشارات مضمنة من التعليمات البرمجية

ضع `backticks` حول الرموز التالية عند استخدامها في النص:

  • أسماء `input` : `input` ، `x` ، `tensor`
  • تم إرجاع أسماء الموتر: `output` `idx` ، `idx` ، `idx` `out`
  • أنواع البيانات: `int32` ، `float` ، `uint8`
  • مرجع أسماء العمليات الأخرى في النص: `list_diff()` ، `shuffle()`
  • أسماء `tf.Tensor` : `tf.Tensor` `Strategy` ، `Strategy`
  • اسم الملف: `image_ops.py` ، `/path_to_dir/file_name`
  • تعبيرات أو شروط `-1-input.dims() <= dim <= input.dims()` : `-1-input.dims() <= dim <= input.dims()`

كتل التعليمات البرمجية

استخدم ثلاث علامات خلفية لفتح وإغلاق كتلة التعليمات البرمجية. اختياريًا ، حدد لغة البرمجة بعد مجموعة backtick الأولى ، على سبيل المثال:


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

استخدم الروابط النسبية بين الملفات في المستودع. يعمل هذا على tensorflow.org و GitHub :
تنتج [Custom layers](../tutorials/eager/custom_layers.ipynb) طبقات مخصصة على الموقع.

يتم تحويل روابط API عند نشر الموقع. للارتباط بصفحة مرجع API الخاصة بالرمز ، قم بتضمين مسار الرمز الكامل في backticks:

بالنسبة لواجهة برمجة تطبيقات C ++ ، استخدم مسار مساحة الاسم:

بالنسبة للروابط الخارجية ، بما في ذلك الملفات الموجودة على https://www.tensorflow.org غير الموجودة في مستودع tensorflow/docs ، استخدم روابط Markdown القياسية مع URI الكامل.

للارتباط بكود المصدر ، استخدم ارتباطًا يبدأ بـ https://www.github.com/tensorflow/tensorflow/blob/master/ ، متبوعًا باسم الملف بدءًا من جذر GitHub.

يضمن نظام تسمية URI هذا أن https://www.tensorflow.org يمكنه إعادة توجيه الرابط إلى فرع الكود المقابل لإصدار الوثائق التي تعرضها.

لا تقم بتضمين معامِلات استعلام URI في الارتباط.

تستخدم مسارات الملفات custom_layers.ipynb السفلية للمسافات ، على سبيل المثال ، custom_layers.ipynb .

قم بتضمين امتداد الملف في الروابط لاستخدامها على الموقع و GitHub ، على سبيل المثال ،
[Custom layers](../tutorials/eager/custom_layers.ipynb) .

الرياضيات في Markdown

يمكنك استخدام 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 دون الارتباط بها. اشرح سبب كتابة الكود بالطريقة التي هي عليه.

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

العمليات

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

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

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

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

موتر

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

لا تستخدم كلمة Tensors (الجمع) لوصف كائنات Tensor متعددة إلا إذا كنت تتحدث بالفعل عن كائن Tensors . بدلاً من ذلك ، قل "قائمة (أو مجموعة) من كائنات Tensor ".

استخدم شكل الكلمة لتفصيل محاور الموتر ، وإظهار الشكل بين قوسين مربعين مع backticks. فمثلا:


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.