Google is committed to advancing racial equity for Black communities. See how.

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

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

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

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

مرجع API

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

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

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

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

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

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

بناء مستندات 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 أدلة و دروس مكتوبة كما تخفيض السعر الملفات والتفاعلية 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 مع المجتمع والموردين لتقديم ترجمات لموقع tensorflow.org. توجد ترجمات دفاتر الملاحظات والمحتويات التقنية الأخرى في Tensorflow / docs-l10n GitHub repo. يرجى إرسال طلبات السحب من خلال مشروع TensorFlow GitLocalize .

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

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

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