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

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

• مرجع API - يتم إنشاء المستندات المرجعية لواجهة برمجة التطبيقات من docstrings في كود مصدر TensorFlow .
• التوثيق السردي —هذه دروس تعليمية وأدلة وكتابات أخرى ليست جزءًا من كود TensorFlow. هذه الوثائق موجودة في مستودع Tensorflow / docs GitHub.
• ترجمات المجتمع - هذه هي الإرشادات والبرامج التعليمية المترجمة من قبل المجتمع. جميع ترجمات المجتمع تعيش في Tensorflow / docs repo.

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

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

• شاهد مستودع GitHub Tensorflow / docs .
• اتبع علامة المستندات في منتدى TensorFlow .

مرجع API

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

النسخ والفروع

يتم تعيين الإصدار المرجعي لواجهة برمجة التطبيقات للموقع افتراضيًا على أحدث ثنائي ثابت — وهذا يطابق الحزمة المثبتة مع 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 والبرامج التعليمية كملفات Markdown ودفاتر ملاحظات 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.