در مستندات TensorFlow مشارکت کنید

TensorFlow از مشارکت در اسناد استقبال می کند - اگر اسناد را بهبود ببخشید، خود کتابخانه TensorFlow را بهبود می بخشید. اسناد موجود در tensorflow.org به دسته‌های زیر تقسیم می‌شوند:

• مرجع API - اسناد مرجع API از رشته‌های اسناد در کد منبع TensorFlow تولید می‌شوند.
• مستندات روایی — اینها آموزش ها ، راهنماها و نوشته های دیگری هستند که بخشی از کد TensorFlow نیستند. این مستندات در مخزن tensorflow/docs GitHub است.
• ترجمه های انجمن — اینها راهنماها و آموزش هایی هستند که توسط انجمن ترجمه شده اند. همه ترجمه‌های انجمن در مخزن tensorflow/docs زندگی می‌کنند.

برخی از پروژه‌های TensorFlow فایل‌های منبع اسناد را در نزدیکی کد در یک مخزن جداگانه، معمولاً در دایرکتوری docs/ نگهداری می‌کنند. فایل CONTRIBUTING.md پروژه را ببینید یا برای مشارکت با نگهدارنده تماس بگیرید.

برای شرکت در انجمن اسناد TensorFlow:

• مخزن tensorflow/docs GitHub را تماشا کنید.
• تگ docs را در تالار گفتمان TensorFlow دنبال کنید.

مرجع API

برای جزئیات، از راهنمای مشارکت‌کننده اسناد TensorFlow API استفاده کنید. این به شما نشان می دهد که چگونه فایل منبع را پیدا کنید و رشته سند نماد را ویرایش کنید. بسیاری از صفحات مرجع API در tensorflow.org دارای پیوندی به فایل منبع هستند که نماد در آن تعریف شده است. Docstrings از Markdown پشتیبانی می‌کند و می‌توان آن را (تقریباً) با استفاده از هر پیش‌نمایش Markdown پیش‌نمایش کرد.

نسخه ها و شاخه ها

نسخه مرجع API سایت به صورت پیش‌فرض روی آخرین باینری پایدار است—این با بسته نصب شده با pip install tensorflow مطابقت دارد.

بسته پیش‌فرض TensorFlow از شاخه پایدار rX.x در مخزن اصلی tensorflow/tensorflow ساخته شده است. مستندات مرجع از نظرات کد و رشته‌های اسناد در کد منبع پایتون ، C++ و جاوا ایجاد می‌شوند.

نسخه های قبلی اسناد 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 Colaboratory در مرورگر شما اجرا کرد. اسناد روایت در tensorflow.org از شاخه master tensorflow/docs ساخته شده‌اند. نسخه‌های قدیمی‌تر در GitHub در شاخه‌های انتشار rX.x در دسترس هستند.

تغییرات ساده

ساده‌ترین راه برای به‌روزرسانی‌های ساده اسناد به فایل‌های Markdown، استفاده از ویرایشگر فایل مبتنی بر وب GitHub است. مخزن tensorflow/docs را مرور کنید تا Markdown را پیدا کنید که تقریباً با ساختار URL tensorflow.org مطابقت دارد. در گوشه سمت راست بالای نمای فایل، روی نماد مداد کلیک کنید برای باز کردن ویرایشگر فایل فایل را ویرایش کنید و سپس یک درخواست کشش جدید ارسال کنید.

یک مخزن Git محلی راه اندازی کنید

برای ویرایش‌های چند فایل یا به‌روزرسانی‌های پیچیده‌تر، بهتر است از یک گردش کار محلی Git برای ایجاد یک درخواست کشش استفاده کنید.

مراحل Git زیر فقط برای اولین بار که یک پروژه محلی را راه اندازی می کنید لازم است.

مخزن tensorflow/docs را فورک کنید

در صفحه 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."

در صورت لزوم، commit های بیشتری اضافه کنید.

3. یک درخواست کشش ایجاد کنید

شعبه محلی خود را در مخزن GitHub راه دور خود آپلود کنید (github.com/ username /docs):

git push

پس از تکمیل فشار، ممکن است پیامی نشانی اینترنتی برای ارسال خودکار درخواست کشش به مخزن بالادستی نمایش دهد. اگر نه، به مخزن tensorflow/docs - یا مخزن خود - بروید و GitHub از شما می‌خواهد که یک درخواست pull ایجاد کنید.

4. مرور کنید

نگهدارنده ها و سایر مشارکت کنندگان درخواست کشش شما را بررسی خواهند کرد. لطفا در بحث شرکت کنید و تغییرات درخواستی را اعمال کنید. هنگامی که درخواست کشش شما تأیید شد، در مخزن اسناد TensorFlow بالادست ادغام خواهد شد.

یک مرحله انتشار جداگانه برای به روز رسانی tensorflow.org از مخزن GitHub وجود دارد. به طور معمول، تغییرات با هم جمع می شوند و سایت بر اساس یک آهنگ منظم به روز می شود.

نوت بوک های تعاملی

در حالی که امکان ویرایش فایل JSON نوت بوک با ویرایشگر فایل مبتنی بر وب GitHub وجود دارد، توصیه نمی شود زیرا JSON ناقص می تواند فایل را خراب کند. قبل از ارسال درخواست کشش، حتما نوت بوک را تست کنید.

Google Colaboratory یک محیط نوت بوک میزبانی شده است که ویرایش و اجرای اسناد نوت بوک را آسان می کند. نوت‌بوک‌ها در GitHub با عبور از مسیر URL Colab در Google 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 Notebook را نصب کرده و ابزار 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 Docs، نوت بوک های بدون سلول های خروجی اجرا و آزمایش می شوند. نوت‌بوک‌هایی که سلول‌های خروجی ذخیره‌شده دارند همانطور که هست منتشر می‌شوند. nbfmt به وضعیت نوت بوک احترام می گذارد و از گزینه --remove_outputs برای حذف صریح سلول های خروجی استفاده می کند.

برای ایجاد یک نوت بوک جدید، الگوی نوت بوک اسناد TensorFlow را کپی و ویرایش کنید.

ویرایش در Colab

در محیط Google Colab، روی سلول‌ها دوبار کلیک کنید تا بلاک‌های متن و کد را ویرایش کنید. سلول های متنی از Markdown استفاده می کنند و باید از راهنمای سبک اسناد TensorFlow پیروی کنند.

فایل های نوت بوک را از Colab با File > Download .pynb دانلود کنید. این فایل را به مخزن Git محلی خود بفرستید و یک درخواست pull ارسال کنید.

برای ایجاد یک نوت بوک جدید، الگوی نوت بوک TensorFlow را کپی و ویرایش کنید.

گردش کار Colab-GitHub

به جای دانلود یک فایل نوت بوک و استفاده از گردش کار محلی Git، می توانید مخزن گیت هاب فورک شده خود را مستقیماً از Google Colab ویرایش و به روز کنید:

1. در مخزن username /docs خود، از رابط وب GitHub برای ایجاد یک شعبه جدید استفاده کنید.
2. برای ویرایش به فایل نوت بوک بروید.
3. نوت بوک را در Google Colab باز کنید: از جایگزین URL یا افزونه Open in Colab Chrome استفاده کنید.
4. نوت بوک را در کولب ویرایش کنید.
5. تغییرات را در مخزن خود از Colab با File > ذخیره یک کپی در GitHub... انجام دهید. گفتگوی ذخیره باید به مخزن و شعبه مناسب پیوند داشته باشد. یک پیام commit معنی دار اضافه کنید.
6. پس از ذخیره، به مخزن خود یا مخزن tensorflow/docs بروید، GitHub باید از شما بخواهد که یک درخواست کشش ایجاد کنید.
7. درخواست کشش توسط نگهبانان بررسی می شود.

ترجمه ها

تیم TensorFlow با جامعه و فروشندگان برای ارائه ترجمه برای tensorflow.org کار می کند. ترجمه‌های نوت‌بوک و سایر محتوای فنی در مخزن tensorflow/docs-l10n GitHub قرار دارند. لطفاً درخواست‌های کشش را از طریق پروژه TensorFlow GitLocalize ارسال کنید.

اسناد انگلیسی منبع حقیقت هستند و ترجمه ها باید تا حد امکان از این راهنماها پیروی کنند. گفته می شود، ترجمه ها برای جوامعی که به آنها خدمت می کنند نوشته می شود. اگر اصطلاحات، عبارات، سبک یا لحن انگلیسی به زبان دیگری ترجمه نمی شود، لطفاً از ترجمه مناسب برای خواننده استفاده کنید.

پشتیبانی زبان توسط تعدادی از عوامل از جمله معیارها و تقاضای سایت، پشتیبانی جامعه، مهارت انگلیسی ، اولویت مخاطب و سایر شاخص‌ها تعیین می‌شود. از آنجایی که هر زبان پشتیبانی شده هزینه دارد، زبان های نگهداری نشده حذف می شوند. پشتیبانی از زبان های جدید در وبلاگ TensorFlow یا توییتر اعلام خواهد شد.

اگر زبان مورد نظر شما پشتیبانی نمی‌شود، می‌توانید یک انجمن انجمن برای مشارکت‌کنندگان منبع باز داشته باشید. اینها در tensorflow.org منتشر نشده اند.