Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

المساهمة في وثائق TensorFlow

ترحب TensorFlow بمساهمات التوثيق - إذا قمت بتحسين الوثائق ، فإنك تقوم بتحسين مكتبة TensorFlow نفسها. تندرج التوثيق على tensorflow.org في الفئات التالية:

تحتفظ بعض مشروعات TensorFlow بملفات مصدر التوثيق بالقرب من الكود في مستودع تخزين منفصل ، عادةً في دليل docs/ . راجع ملف CONTRIBUTING.md الخاص بالمشروع أو اتصل بالمشرف للمساهمة.

للمشاركة في مجتمع مستندات TensorFlow:

مرجع API

لتحديث الوثائق المرجعية ، ابحث عن الملف المصدر وقم بتحرير سلسلة docstring الخاصة بالرمز. تتضمن العديد من صفحات مرجعية API على tensorflow.org ارتباطًا إلى الملف المصدر حيث يتم تعريف الرمز. جمل التوثيق تدعم تخفيض السعر ، ويمكن (تقريبا) معاينتها باستخدام أي المعاين تخفيض السعر .

للحصول على جودة الوثائق المرجعية وكيفية المشاركة في سباقات المستندات والمجتمع ، راجع نصيحة محرر مستندات TensorFlow 2 API .

الإصدارات والفروع

يتم تعيين الإصدار المرجعي لواجهة برمجة التطبيقات للموقع افتراضيًا على أحدث ثنائي ثابت — وهذا يطابق الحزمة المثبتة مع pip install tensorflow .

تم إنشاء حزمة TensorFlow الافتراضية من الفرع المستقر rX.x في tensorflow / tensorflow repo الرئيسي. يتم إنشاء الوثائق المرجعية من تعليقات التعليمات البرمجية وسلاسل المستندات في التعليمات البرمجية المصدر لـ Python و C ++ و Java .

تتوفر الإصدارات السابقة من وثائق TensorFlow كفروع rX.x في مستودع مستندات TensorFlow. تتم إضافة هذه الفروع عند إصدار إصدار جديد.

بناء مستندات API

مرجع بايثون

تتضمن حزمة tensorflow_docs المولد للمستندات المرجعية لواجهة برمجة تطبيقات Python . لتثبيت:

pip install git+https://github.com/tensorflow/docs

لإنشاء المستندات المرجعية TensorFlow 2 ، استخدم البرنامج النصي tensorflow/tools/docs/generate2.py :

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

التوثيق السردي

TensorFlow أدلة و دروس مكتوبة كما تخفيض السعر الملفات والتفاعلية Jupyter أجهزة الكمبيوتر المحمولة. يمكن تشغيل أجهزة الكمبيوتر المحمول في متصفحك باستخدام Google Colaboratory . تم إنشاء المستندات السردية على tensorflow.org من الفرع master tensorflow / docs . تتوفر الإصدارات الأقدم في GitHub في فروع إصدار rX.x

تغييرات بسيطة

تتمثل أسهل طريقة لإجراء تحديثات توثيق مباشرة على ملفات Markdown في استخدام محرر الملفات المستند إلى الويب في GitHub. تصفح مستودع tensorflow / docs للعثور على Markdown الذي يتوافق تقريبًا مع بنية عنوان URL لـ tensorflow.org . في الزاوية العلوية اليمنى من عرض الملف ، انقر على رمز القلم الرصاص لفتح محرر الملف. قم بتحرير الملف ثم قم بتقديم طلب سحب جديد.

قم بإعداد Git repo محلي

بالنسبة إلى عمليات تحرير الملفات المتعددة أو التحديثات الأكثر تعقيدًا ، من الأفضل استخدام سير عمل Git محلي لإنشاء طلب سحب.

خطوات Git التالية مطلوبة فقط في المرة الأولى التي تقوم فيها بإعداد مشروع محلي.

شوكة tensorflow / docs repo

في صفحة Tensorflow / docs GitHub ، انقر فوق الزر Fork لإنشاء نسخة الريبو الخاصة بك تحت حساب GitHub الخاص بك. بمجرد التفرع ، فأنت مسؤول عن الحفاظ على تحديث نسخة الريبو الخاصة بك من خلال ريبو TensorFlow المنبع.

استنساخ الريبو الخاص بك

تحميل نسخة من البريد البعيد username / مستندات الريبو إلى الجهاز المحلي. هذا هو دليل العمل حيث ستقوم بإجراء التغييرات:

git clone git@github.com:username/docs
cd ./docs

إضافة الريبو المنبع للبقاء محدثًا (اختياري)

للحفاظ على تزامن المستودع المحلي مع tensorflow/docs ، أضف جهاز تحكم عن بعد في المنبع لتنزيل أحدث التغييرات.

أضف جهاز تحكم عن بعد:

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

للتحديث:

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

سير عمل GitHub

1. إنشاء فرع جديد

بعد تحديث الريبو الخاص بك من tensorflow/docs ، قم بإنشاء فرع جديد من الفرع الرئيسي المحلي:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. قم بإجراء التغييرات

قم بتحرير الملفات في المحرر المفضل لديك ويرجى اتباع دليل أسلوب التوثيق TensorFlow .

التزم بتغيير ملفك:

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

أضف المزيد من الالتزامات حسب الضرورة.

3. إنشاء طلب سحب

قم بتحميل فرعك المحلي إلى GitHub repo (github.com/ username / docs):

git push

بعد اكتمال الدفع ، قد تعرض رسالة عنوان URL لإرسال طلب سحب تلقائيًا إلى الريبو المنبع. إذا لم يكن كذلك ، فانتقل إلى tensorflow / docs repo - أو الريبو الخاص بك - وسيطالبك GitHub بإنشاء طلب سحب.

4. المراجعة

سيقوم المشرفون على الصيانة والمساهمون الآخرون بمراجعة طلب السحب الخاص بك. يرجى المشاركة في المناقشة وإجراء التغييرات المطلوبة. عند الموافقة على طلب السحب الخاص بك ، سيتم دمجه في مستودع مستندات TensorFlow المنبع.

هناك خطوة نشر منفصلة لتحديث tensorflow.org من GitHub repo. عادةً ، يتم تجميع التغييرات معًا ويتم تحديث الموقع بإيقاع منتظم.

دفاتر تفاعلية

على الرغم من أنه من الممكن تحرير ملف JSON الخاص بالكمبيوتر الدفتري باستخدام محرر الملفات المستند إلى الويب الخاص بـ GitHub ، إلا أنه لا يوصى بذلك نظرًا لأن JSON المشوه يمكن أن يفسد الملف. تأكد من اختبار الكمبيوتر الدفتري قبل إرسال طلب سحب.

إن Google Colaboratory عبارة عن بيئة دفتر ملاحظات مستضافة تسهل تعديل - وتشغيل - وثائق الكمبيوتر الدفتري. يتم تحميل أجهزة الكمبيوتر المحمولة في GitHub في Google Colab عن طريق تمرير المسار إلى عنوان URL الخاص بـ Colab ، على سبيل المثال ، دفتر الملاحظات الموجود في GitHub هنا: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
يمكن تحميلها إلى Google Colab على عنوان URL هذا: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

يوجد ملحق Open in Colab Chrome يقوم باستبدال عنوان URL هذا عند تصفح جهاز كمبيوتر محمول على GitHub. يكون هذا مفيدًا عند فتح دفتر ملاحظات في مفترق إعادة الشراء ، لأن الأزرار العلوية ترتبط دائمًا بالفرع master TensorFlow Docs.

تنسيق دفتر الملاحظات

أداة تنسيق دفتر الملاحظات تجعل مصدر دفتر ملاحظات Jupyter متناسقًا ويسهل مراجعته. نظرًا لاختلاف بيئات تأليف دفتر الملاحظات فيما يتعلق بإخراج الملف والمسافة البادئة والبيانات الوصفية وغيرها من الحقول غير المحددة ؛ يستخدم nbfmt الإعدادات الافتراضية التي لها رأي مع تفضيل سير عمل مستندات TensorFlow Colab. لتنسيق دفتر ملاحظات ، ثبّت أدوات دفتر ملاحظات مستندات TensorFlow وقم بتشغيل الأداة nbfmt :

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

بالنسبة لمشروعات مستندات TensorFlow ، يتم تنفيذ واختبار دفاتر الملاحظات التي لا تحتوي على خلايا إخراج ؛ وتنشر أجهزة الكمبيوتر المحمولة مع خلايا الناتج حفظها كما هو. يحترم nbfmt حالة دفتر الملاحظات ويستخدم الخيار --remove_outputs لإزالة خلايا الإخراج بشكل صريح.

لإنشاء دفتر ملاحظات جديد ، قم بنسخ قالب دفتر ملاحظات مستندات TensorFlow وتحريره .

تحرير في Colab

داخل بيئة Google Colab ، انقر نقرًا مزدوجًا فوق الخلايا لتحرير النص وكتل التعليمات البرمجية. تستخدم الخلايا النصية Markdown ويجب أن تتبع دليل نمط مستندات TensorFlow .

قم بتنزيل ملفات دفتر الملاحظات من Colab باستخدام ملف> تنزيل .pynb . قم بإيداع هذا الملف في Git repo المحلي الخاص بك وأرسل طلب سحب.

لإنشاء دفتر ملاحظات جديد ، قم بنسخ قالب دفتر ملاحظات TensorFlow وتحريره .

سير عمل Colab-GitHub

بدلاً من تنزيل ملف دفتر ملاحظات واستخدام سير عمل Git محلي ، يمكنك تحرير وتحديث GitHub repo الخاص بك مباشرةً من Google Colab:

  1. في username / مستودع المستندات المتشعب ، استخدم واجهة مستخدم الويب GitHub لإنشاء فرع جديد .
  2. انتقل إلى ملف دفتر الملاحظات للتحرير.
  3. افتح دفتر الملاحظات في Google Colab: استخدم مبادلة URL أو ملحق Open in Colab Chrome.
  4. قم بتحرير دفتر الملاحظات في Colab.
  5. قم بتنفيذ التغييرات على الريبو الخاص بك من Colab باستخدام ملف> حفظ نسخة في GitHub .... يجب أن يرتبط مربع حوار الحفظ بـ الريبو والفرع المناسبين. أضف رسالة التزام ذات مغزى.
  6. بعد الحفظ ، استعرض للوصول إلى الريبو أو tensorflow / docs repo ، يجب أن يطالبك GitHub بإنشاء طلب سحب.
  7. تتم مراجعة طلب السحب من قبل المشرفين.

ترجمات المجتمع

تعتبر ترجمات المجتمع طريقة رائعة لجعل TensorFlow متاحًا في جميع أنحاء العالم. لتحديث ترجمة ، ابحث عن ملف أو أضفه في دليل اللغة الذي يطابق نفس بنية الدليل en/ . المستندات الإنجليزية هي مصدر الحقيقة ويجب أن تتبع الترجمات هذه الأدلة في أقرب وقت ممكن. ومع ذلك ، تتم كتابة الترجمات للمجتمعات التي تخدمها. إذا كانت المصطلحات الإنجليزية أو الصياغة أو الأسلوب أو النبرة لا تترجم إلى لغة أخرى ، فيرجى استخدام ترجمة مناسبة للقارئ.

هناك مجموعات مستندات خاصة بلغة معينة تسهل على المساهمين في الترجمة تنظيمها. يرجى الانضمام إذا كنت مؤلفًا أو مراجعًا أو مهتمًا فقط ببناء محتوى TensorFlow.org للمجتمع:

مراجعة الإخطارات

تتطلب كافة تحديثات الوثائق مراجعة. للتعاون بشكل أكثر كفاءة مع مجتمعات الترجمة TensorFlow ، إليك بعض الطرق لمتابعة النشاط الخاص باللغة:

  • انضم إلى مجموعة لغة مدرجة أعلاه لتلقي بريد إلكتروني لأي طلب سحب تم إنشاؤه يلامس دليل site/ lang لتلك اللغة.
  • أضف اسم مستخدم GitHub الخاص بك إلى ملف site/<lang>/REVIEWERS للحصول على علامة تعليق تلقائيًا في طلب سحب. عند وضع علامة على التعليق ، سيرسل لك GitHub إشعارات بجميع التغييرات والمناقشة في طلب السحب هذا.

حافظ على تحديث التعليمات البرمجية في الترجمات

بالنسبة لمشروع مفتوح المصدر مثل TensorFlow ، فإن تحديث الوثائق يمثل تحديًا. بعد التحدث مع المجتمع ، سيتسامح قراء المحتوى المترجم مع النص القديم إلى حد ما ، ولكن الشفرة القديمة أمر محبط. لتسهيل مزامنة التعليمات البرمجية ، استخدم أداة nb-code-sync لدفاتر الملاحظات المترجمة:

./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb

يقوم هذا البرنامج النصي بقراءة خلايا التعليمات البرمجية الخاصة بدفتر اللغة والتحقق منها مقابل النسخة الإنجليزية. بعد تجريد التعليقات ، يقوم بمقارنة كتل التعليمات البرمجية وتحديث دفتر اللغة إذا كانت مختلفة. هذه الأداة مفيدة بشكل خاص مع سير عمل git التفاعلي لإضافة أجزاء من الملف بشكل انتقائي إلى الالتزام باستخدام: git add --patch site/lang/notebook.ipynb