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

به اسناد TensorFlow کمک کنید

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

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

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

مرجع API

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

برای اطلاع از کیفیت اسناد مرجع و چگونگی درگیر شدن با doc sprints و انجمن ، به توصیه TensorFlow 2 API Docs مراجعه کنید .

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

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

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

نسخه های قبلی مستندات TensorFlow به عنوان شاخه های rX.x در مخزن TensorFlow Docs در دسترس هستند. این شاخه ها با انتشار نسخه جدید اضافه می شوند.

ساخت اسناد API

مرجع پایتون

بسته tensorflow_docs شامل مولد اسناد مرجع Python API است . برای نصب:

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

برای تولید اسناد مرجع tensorflow/tools/docs/generate2.py 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 / اسناد repo

در صفحه tensorflow / docs GitHub ، روی دکمه Fork کلیک کنید برای ایجاد کپی مجدد خود در حساب GitHub خود. پس از انشعاب ، شما مسئول به روز نگه داشتن کپی مخزن خود با نسخه ی نمایشی بالادستی TensorFlow هستید.

repo خود را کلون کنید

نسخه ای از 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. یک شاخه جدید ایجاد کنید

بعد از اینکه repo خود را از 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. درخواست کشش ایجاد کنید

شعبه محلی خود را در repo GitHub از راه دور خود بارگذاری کنید (github.com/ username / اسناد):

git push

پس از اتمام فشار ، ممکن است یک پیام URL را نمایش دهد تا به طور خودکار درخواست کشش را به repo بالادستی ارسال کند. در غیر اینصورت ، به repo tensorflow / docs - یا repo شخصی خود - بروید و GitHub از شما درخواست می کند که یک درخواست کشش ایجاد کنید.

4. مرور کنید

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

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

دفترهای تعاملی

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

Google Colaborator یک محیط نوت بوک میزبان است که ویرایش و اجرای مستندات نوت بوک را آسان می کند. نوت بوک های موجود در GitHub با عبور از مسیر به URL Colab در Google Colab بارگذاری می شوند ، به عنوان مثال نوت بوکی که در GitHub واقع شده است: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
از طریق این URL می توانید در Google Colab بارگیری کنید: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

پسوند Open in Colab Chrome وجود دارد که هنگام مرور یک دفترچه یادداشت در GitHub ، این جایگزینی URL را انجام می دهد. این هنگام باز کردن یک نوت بوک در چنگال repo شما مفید است ، زیرا دکمه های بالا همیشه به شاخه master TensorFlow Docs پیوند دارند.

قالب بندی نوت بوک

یک ابزار قالب بندی نوت بوک باعث می شود منبع نوت بوک Jupyter متفاوت باشد و بررسی آن آسان تر باشد. از آنجا که محیط های نوشتن نوت بوک از نظر خروجی پرونده ، تورفتگی ، فراداده و سایر زمینه های نامشخص متفاوت هستند. nbfmt با استفاده از پیش فرض های nbfmt با اولویت گردش کار nbfmt استفاده می کند. برای قالب بندی یک نوت بوک ، ابزارهای نوت بوک nbfmt 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 را کپی و ویرایش کنید .

ویرایش در Colab

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

پرونده های نوت بوک را از Colab با File> Download .pynb بارگیری کنید . این پرونده را به repo محلی Git خود متعهد کنید و درخواست جلب کنید.

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

گردش کار Colab-GitHub

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

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

ترجمه ها

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

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

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

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