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

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

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

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

مرجع API

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

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

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

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

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

إنشاء مستندات API

مرجع بايثون

تتضمن حزمة tensorflow_docs منشئ المستندات المرجعية لـ Python API . للتثبيت:

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 والبرامج التعليمية كملفات Markdown ودفاتر Jupyter التفاعلية. يمكن تشغيل دفاتر الملاحظات في متصفحك باستخدام Google Collaboratory . تم إنشاء المستندات السردية على Tensorflow.org من الفرع master Tensorflow/docs . تتوفر الإصدارات الأقدم في GitHub في فروع إصدار rX.x

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

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

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

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

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

شوكة مستودع Tensorflow/docs

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

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

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

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)

سير عمل جيثب

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 docs Colab. لتنسيق دفتر ملاحظات، قم بتثبيت أدوات دفتر ملاحظات TensorFlow docs وقم بتشغيل أداة 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 docs وقم بتحريره.

تحرير في كولاب

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

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

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

سير عمل Colab-GitHub

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

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

ترجمات

يعمل فريق TensorFlow مع المجتمع والموردين لتوفير ترجمات لـ Tensorflow.org. توجد ترجمات دفاتر الملاحظات والمحتويات الفنية الأخرى في Tensorflow/docs-l10n GitHub repo. يرجى إرسال طلبات السحب من خلال مشروع TensorFlow GitLocalize .

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

يتم تحديد دعم اللغة من خلال عدد من العوامل بما في ذلك - على سبيل المثال لا الحصر - مقاييس الموقع والطلب، ودعم المجتمع، وإتقان اللغة الإنجليزية ، وتفضيلات الجمهور، ومؤشرات أخرى. نظرًا لأن كل لغة مدعومة تتحمل تكلفة، تتم إزالة اللغات غير المدعومة. سيتم الإعلان عن دعم اللغات الجديدة على مدونة TensorFlow أو Twitter .

إذا كانت لغتك المفضلة غير مدعومة، فنحن نرحب بك للاحتفاظ بشوكة مجتمعية للمساهمين مفتوحي المصدر. لم يتم نشرها على Tensorflow.org.