תרום לתיעוד TensorFlow

TensorFlow מקבל בברכה תרומות לתיעוד - אם אתה משפר את התיעוד, אתה משפר את ספריית TensorFlow עצמה. התיעוד באתר tensorflow.org נכלל בקטגוריות הבאות:

חלק מפרויקטי TensorFlow שומרים קבצי מקור תיעוד ליד הקוד במאגר נפרד, בדרך כלל בספריית docs/ . עיין בקובץ CONTRIBUTING.md של הפרויקט או פנה למנהל כדי לתרום.

כדי להשתתף בקהילת המסמכים של TensorFlow:

הפניה ל-API

לפרטים, השתמש במדריך התורמים למסמכים של TensorFlow API . זה מראה לך כיצד למצוא את קובץ המקור ולערוך את המחרוזת של הסמל . דפי עזר רבים של API ב-tensorflow.org כוללים קישור לקובץ המקור שבו הסמל מוגדר. מחרוזות Docstrings תומכות ב-Markdown וניתן לצפות בהן (בקירוב) באמצעות כל תצוגה מקדימה של Markdown .

גרסאות וענפים

ברירת המחדל של גרסת ההתייחסות ל-API של האתר היא הבינארי היציב העדכני ביותר - זה תואם את החבילה המותקנת עם pip install tensorflow .

חבילת ברירת המחדל של TensorFlow בנויה מהענף היציב rX.x ב- tensorflow/tensorflow repo הראשי. תיעוד ההפניה נוצר מהערות קוד וממחרוזות docstrings בקוד המקור עבור 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 שמתאים בערך למבנה כתובת האתר של tensorflow.org . בפינה השמאלית העליונה של תצוגת הקובץ, לחץ על סמל העיפרון כדי לפתוח את עורך הקבצים. ערוך את הקובץ ולאחר מכן שלח בקשת משיכה חדשה.

הגדר מאגר Git מקומי

עבור עריכות מרובות קבצים או עדכונים מורכבים יותר, עדיף להשתמש בזרימת עבודה מקומית של Git כדי ליצור בקשת משיכה.

השלבים הבאים של Git נדרשים רק בפעם הראשונה שאתה מגדיר פרויקט מקומי.

מזלג את המאגר של tensorflow/docs

בדף tensorflow/docs GitHub, לחץ על הלחצן Fork כדי ליצור עותק ריפו משלך תחת חשבון GitHub שלך. לאחר התפצלות, אתה אחראי לעדכן את עותק ה-repo שלך עם ה-Repo של 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)

זרימת עבודה של 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. צור בקשת משיכה

העלה את הסניף המקומי שלך למאגר GitHub המרוחק שלך (github.com/ username /docs):

git push

לאחר השלמת הדחיפה, הודעה עשויה להציג כתובת URL להגשת בקשת משיכה אוטומטית לריפו במעלה הזרם. אם לא, עבור ל-tensorflow/docs repo - או לריפו משלך - ו-GitHub ינחה אותך ליצור בקשת משיכה.

4. סקירה

מתחזקים ותורמים אחרים יבדקו את בקשת המשיכה שלך. נא להשתתף בדיון ולבצע את השינויים המבוקשים. כאשר בקשת המשיכה שלך תאושר, היא תתמזג למאגר המסמכים של TensorFlow במעלה הזרם.

ישנו שלב פרסום נפרד לעדכון tensorflow.org מהריפו של GitHub. בדרך כלל, שינויים מצטברים יחד והאתר מתעדכן בקצב קבוע.

מחברות אינטראקטיביות

אמנם אפשר לערוך את קובץ ה-JSON של המחברת עם עורך הקבצים מבוסס האינטרנט של GitHub, אבל זה לא מומלץ מכיוון ש-JSON פגום עלול להשחית את הקובץ. הקפד לבדוק את המחברת לפני הגשת בקשת משיכה.

Google Collaboratory היא סביבת מחברת מתארחת שמקלה לערוך - ולהפעיל - תיעוד מחברת. מחברות ב-GitHub נטענות ב-Google Colab על ידי העברת הנתיב לכתובת ה-URL של Colab, לדוגמה, המחברת הממוקמת ב-GitHub כאן: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
ניתן לטעון ל-Google Colab בכתובת האתר הזו: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

יש תוסף Open in Colab Chrome שמבצע את החלפת כתובת האתר הזו בעת גלישה במחברת ב-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 docs, מחברות ללא תאי פלט מבוצעות ונבדקות; מחברות עם תאי פלט שמורים מתפרסמות כפי שהן. nbfmt מכבד את מצב המחברת ומשתמש באפשרות --remove_outputs כדי להסיר באופן מפורש תאי פלט.

כדי ליצור מחברת חדשה, העתק וערוך את תבנית המחברת TensorFlow docs .

ערוך ב-Colab

בתוך סביבת Google Colab, לחץ פעמיים על תאים כדי לערוך בלוקי טקסט וקוד. תאי טקסט משתמשים ב-Markdown וצריכים לפעול בהתאם למדריך הסגנונות של TensorFlow docs .

הורד קבצי מחברת מ-Colab באמצעות קובץ > הורד .pynb . העבר את הקובץ הזה למאגר Git המקומי שלך ושלח בקשת משיכה.

כדי ליצור מחברת חדשה, העתק וערוך את תבנית המחברת TensorFlow .

זרימת עבודה של Colab-GitHub

במקום להוריד קובץ מחברת ולהשתמש בזרימת עבודה מקומית של Git, אתה יכול לערוך ולעדכן את מאגר ה-GitHub המפוצל שלך ישירות מ-Google Colab:

  1. במאגר ה-Forked username /docs שלך, השתמש בממשק האינטרנט של GitHub כדי ליצור סניף חדש .
  2. נווט אל קובץ המחברת כדי לערוך.
  3. פתח את המחברת ב-Google Colab: השתמש בהחלפת כתובת האתר או בתוסף פתח ב-Colab Chrome.
  4. ערוך את המחברת ב-Colab.
  5. בצע את השינויים בריפו שלך מ-Colab עם קובץ > שמור עותק ב-GitHub... . תיבת הדו-שיח של השמירה צריכה לקשר לריפו ולסניף המתאימים. הוסף הודעת התחייבות משמעותית.
  6. לאחר השמירה, דפדף לריפו שלך או ל- tensorflow/docs repo, GitHub אמור לבקש ממך ליצור בקשת משיכה.
  7. בקשת המשיכה נבדקת על ידי מתחזקים.

תרגומים

צוות TensorFlow עובד עם הקהילה ועם הספקים כדי לספק תרגומים עבור tensorflow.org. תרגומים של מחברות ותכנים טכניים אחרים נמצאים ב- tensorflow/docs-l10n GitHub. נא לשלוח בקשות משיכה דרך פרויקט TensorFlow GitLocalize .

המסמכים באנגלית הם מקור האמת ועל התרגומים לעקוב אחר המדריכים הללו קרוב ככל האפשר. עם זאת, תרגומים נכתבים עבור הקהילות שהם משרתים. אם המינוח, הביטוי, הסגנון או הטון באנגלית אינם מתורגמים לשפה אחרת, אנא השתמש בתרגום המתאים לקורא.

תמיכת השפה נקבעת על ידי מספר גורמים, כולל - אך לא רק - מדדי אתר וביקוש, תמיכה בקהילה, שליטה באנגלית , העדפת קהל ואינדיקטורים אחרים. מכיוון שכל שפה נתמכת כרוכה בעלות, שפות שאינן מתוחזקות מוסרות. תמיכה בשפות חדשות תוכרז בבלוג TensorFlow או בטוויטר .

אם השפה המועדפת עליך אינה נתמכת, אתה מוזמן לתחזק מזלג קהילתי עבור תורמים בקוד פתוח. אלה אינם מפורסמים ב-tensorflow.org.