มีส่วนร่วมในเอกสาร TensorFlow

TensorFlow ยินดีสนับสนุนการมีส่วนร่วมด้านเอกสาร หากคุณปรับปรุงเอกสาร เท่ากับคุณปรับปรุงไลบรารี TensorFlow เอง เอกสารบน tensorflow.org แบ่งออกเป็นหมวดหมู่ต่อไปนี้:

  • การอ้างอิง API — เอกสารอ้างอิง API สร้างขึ้นจากสตริงเอกสารใน ซอร์สโค้ด TensorFlow
  • เอกสารประกอบการบรรยาย —นี่คือ บทช่วยสอน คำแนะนำ และงานเขียนอื่นๆ ที่ไม่ได้เป็นส่วนหนึ่งของโค้ด TensorFlow เอกสารนี้อยู่ในพื้นที่เก็บข้อมูล GitHub ของ tensorflow/docs
  • การแปลโดยชุมชน — นี่คือคำแนะนำและบทช่วยสอนที่แปลโดยชุมชน การแปลชุมชนทั้งหมดอยู่ใน repo tensorflow/docs

โปรเจ็กต์ TensorFlow บางโปรเจ็กต์เก็บไฟล์ต้นฉบับเอกสารไว้ใกล้กับโค้ดในพื้นที่เก็บข้อมูลแยกต่างหาก ซึ่งโดยปกติจะอยู่ในไดเร็กทอรี docs/ ดูไฟล์ CONTRIBUTING.md ของโครงการหรือติดต่อผู้ดูแลเพื่อมีส่วนร่วม

หากต้องการเข้าร่วมในชุมชนเอกสาร TensorFlow:

การอ้างอิง API

สำหรับรายละเอียด ให้ใช้ คู่มือผู้สนับสนุนเอกสาร TensorFlow API ข้อมูลนี้แสดงวิธีค้นหา ไฟล์ต้นฉบับ และแก้ไข docstring ของสัญลักษณ์ หน้าอ้างอิง API หลายหน้าบน tensorflow.org มีลิงก์ไปยังไฟล์ต้นฉบับที่มีการกำหนดสัญลักษณ์ไว้ Docstrings รองรับ Markdown และสามารถดูตัวอย่าง (โดยประมาณ) ได้โดยใช้ โปรแกรมดูตัวอย่าง Markdown ใดก็ได้

รุ่นและสาขา

เวอร์ชัน อ้างอิง API ของเว็บไซต์มีค่าเริ่มต้นเป็นไบนารี่ที่เสถียรล่าสุด ซึ่งตรงกับแพ็คเกจที่ติดตั้งด้วย pip install tensorflow

แพ็คเกจ TensorFlow เริ่มต้นสร้างขึ้นจากสาขา rX.x ที่เสถียรใน repo tensorflow/tensorflow หลัก เอกสารอ้างอิงถูกสร้างขึ้นจากความคิดเห็นของโค้ดและสตริงเอกสารในซอร์สโค้ดสำหรับ 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 Colaboratory เอกสารการเล่าเรื่องบน tensorflow.org สร้างขึ้นจากสาขา master tensorflow/docs เวอร์ชันเก่าๆ มีอยู่ใน GitHub บนสาขาการเผยแพร่ rX.x

การเปลี่ยนแปลงง่ายๆ

วิธีที่ง่ายที่สุดในการอัปเดตเอกสารที่ตรงไปตรงมาสำหรับไฟล์ Markdown คือการใช้ โปรแกรมแก้ไขไฟล์บนเว็บ ของ GitHub เรียกดูพื้นที่เก็บข้อมูล tensorflow/docs เพื่อค้นหา Markdown ที่สอดคล้องกับโครงสร้าง URL ของ tensorflow.org โดยประมาณ ที่มุมขวาบนของมุมมองไฟล์ ให้คลิกไอคอนดินสอ เพื่อเปิดตัวแก้ไขไฟล์ แก้ไขไฟล์แล้วส่งคำขอดึงใหม่

ตั้งค่า repo Git ในเครื่อง

สำหรับการแก้ไขหลายไฟล์หรือการอัปเดตที่ซับซ้อนยิ่งขึ้น ควรใช้เวิร์กโฟลว์ Git ในเครื่องเพื่อสร้างคำขอดึง

ขั้นตอน Git ต่อไปนี้จำเป็นเฉพาะในครั้งแรกที่คุณตั้งค่าโปรเจ็กต์ในเครื่องเท่านั้น

แยก repo tensorflow/docs

ในหน้า tensorflow/docs GitHub ให้คลิกปุ่ม Fork เพื่อสร้างสำเนา repo ของคุณเองภายใต้บัญชี GitHub ของคุณ เมื่อแยกทางแล้ว คุณจะต้องรับผิดชอบในการอัปเดตสำเนา Repo ของคุณให้เป็นปัจจุบันด้วย TensorFlow Repo อัปสตรีม

โคลน repo ของคุณ

ดาวน์โหลดสำเนา ชื่อ username ระยะไกล /docs repo ไปยังเครื่องของคุณ นี่คือไดเร็กทอรีการทำงานที่คุณจะทำการเปลี่ยนแปลง:

git clone git@github.com:username/docs
cd ./docs

เพิ่ม repo อัปสตรีมเพื่อให้ทันสมัยอยู่เสมอ (ไม่บังคับ)

หากต้องการให้ที่เก็บข้อมูลในเครื่องของคุณซิงค์กับ 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 /docs):

git push

หลังจากการพุชเสร็จสิ้น ข้อความอาจแสดง URL เพื่อส่งคำขอดึงไปยัง repo อัพสตรีมโดยอัตโนมัติ ถ้าไม่ ให้ไปที่ tensorflow/docs repo—หรือ repo ของคุณเอง—แล้ว GitHub จะแจ้งให้คุณสร้างคำขอดึง

4. ทบทวน

ผู้ดูแลและผู้มีส่วนร่วมอื่นๆ จะตรวจสอบคำขอดึงของคุณ กรุณามีส่วนร่วมในการสนทนาและทำการเปลี่ยนแปลงตามที่ร้องขอ เมื่อคำขอดึงของคุณได้รับการอนุมัติ คำขอนั้นจะถูกรวมเข้ากับที่เก็บเอกสารอัปสตรีม TensorFlow

มีขั้นตอนการเผยแพร่แยกต่างหากเพื่ออัปเดต tensorflow.org จาก repo GitHub โดยทั่วไปแล้ว การเปลี่ยนแปลงจะถูกรวมเข้าด้วยกันและไซต์จะได้รับการอัปเดตตามจังหวะปกติ

สมุดบันทึกแบบโต้ตอบ

แม้ว่าจะสามารถแก้ไขไฟล์ JSON ของสมุดบันทึกด้วย โปรแกรมแก้ไขไฟล์บนเว็บ ของ GitHub ได้ แต่ไม่แนะนำเนื่องจาก JSON ที่มีรูปแบบไม่ถูกต้องอาจทำให้ไฟล์เสียหายได้ อย่าลืมทดสอบโน้ตบุ๊กก่อนส่งคำขอดึง

Google Colaboratory คือสภาพแวดล้อมโน้ตบุ๊กที่โฮสต์ ซึ่งช่วยให้แก้ไขและเรียกใช้เอกสารโน้ตบุ๊กได้ง่าย สมุดบันทึกใน GitHub ถูกโหลดใน Google Colab โดยส่งเส้นทางไปยัง Colab URL ตัวอย่างเช่นสมุดบันทึกที่อยู่ใน 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 สิ่งนี้มีประโยชน์เมื่อเปิดสมุดบันทึกใน repo fork ของคุณ เนื่องจากปุ่มด้านบนจะเชื่อมโยงกับสาขา master TensorFlow Docs เสมอ

การจัดรูปแบบสมุดบันทึก

เครื่องมือจัดรูปแบบสมุดบันทึกทำให้แหล่งที่มาของสมุดบันทึก Jupyter มีความสอดคล้องกันและง่ายต่อการตรวจสอบ เนื่องจากสภาพแวดล้อมการเขียนโน้ตบุ๊กแตกต่างกันโดยคำนึงถึงเอาท์พุตไฟล์ การเยื้อง ข้อมูลเมตา และฟิลด์อื่นๆ ที่ไม่ได้ระบุ nbfmt ใช้ค่าเริ่มต้นที่กำหนดโดยมีค่ากำหนดสำหรับเวิร์กโฟลว์ Colab ของเอกสาร TensorFlow หากต้องการฟอร์แมตสมุดบันทึก ให้ติดตั้ง เครื่องมือสมุดบันทึกเอกสาร 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 ด้วย File > Download .pynb ส่งไฟล์นี้ไปยัง repo Git ในพื้นที่ ของคุณและส่งคำขอดึง

หากต้องการสร้างสมุดบันทึกใหม่ ให้คัดลอกและแก้ไข เทมเพลตสมุดบันทึก TensorFlow

เวิร์กโฟลว์ Colab-GitHub

แทนที่จะดาวน์โหลดไฟล์สมุดบันทึกและใช้เวิร์กโฟลว์ Git ในเครื่อง คุณสามารถแก้ไขและอัปเดต repo GitHub ที่แยกออกมาได้โดยตรงจาก Google Colab:

  1. ใน username /docs repo ที่แยกออกมาของคุณ ให้ใช้ GitHub web UI เพื่อ สร้างสาขาใหม่
  2. นำทางไปยังไฟล์สมุดบันทึกเพื่อแก้ไข
  3. เปิดสมุดบันทึกใน Google Colab: ใช้การสลับ URL หรือส่วนขยาย Open in Colab Chrome
  4. แก้ไขสมุดบันทึกใน Colab
  5. ยอมรับการเปลี่ยนแปลง repo ของคุณจาก Colab ด้วย File > Save a copy in GitHub... กล่องโต้ตอบบันทึกควรลิงก์ไปยัง repo และสาขาที่เหมาะสม เพิ่มข้อความยืนยันที่มีความหมาย
  6. หลังจากบันทึก ให้เรียกดู repo ของคุณหรือ repo tensorflow/docs GitHub ควรแจ้งให้คุณสร้างคำขอดึง
  7. คำขอดึงได้รับการตรวจสอบโดยผู้ดูแล

การแปล

ทีม TensorFlow ทำงานร่วมกับชุมชนและผู้ขายเพื่อให้บริการแปลสำหรับ tensorflow.org การแปลสมุดบันทึกและเนื้อหาทางเทคนิคอื่นๆ มีอยู่ใน repo tensorflow/docs-l10n GitHub โปรดส่งคำขอดึงผ่าน โปรเจ็กต์ TensorFlow GitLocalize

เอกสารภาษาอังกฤษเป็น แหล่งที่มาของความจริง และคำแปลควรเป็นไปตามคำแนะนำเหล่านี้ให้ใกล้เคียงที่สุด กล่าวคือ มีการเขียนคำแปลสำหรับชุมชนที่พวกเขาให้บริการ หากคำศัพท์ การใช้ถ้อยคำ รูปแบบ หรือน้ำเสียงภาษาอังกฤษไม่ได้แปลเป็นภาษาอื่น โปรดใช้คำแปลที่เหมาะสมสำหรับผู้อ่าน

การสนับสนุนด้านภาษาถูกกำหนดโดยปัจจัยหลายประการ รวมถึง (แต่ไม่จำกัดเพียง) ตัวชี้วัดและความต้องการของไซต์ การสนับสนุนของชุมชน ความสามารถทางภาษาอังกฤษ ความชอบของผู้ชม และตัวชี้วัดอื่น ๆ เนื่องจากแต่ละภาษาที่รองรับมีค่าใช้จ่าย ภาษาที่ไม่ได้รับการดูแลจึงถูกลบออก การสนับสนุนภาษาใหม่จะมีการประกาศใน บล็อก TensorFlow หรือ Twitter

หากภาษาที่คุณต้องการไม่รองรับ คุณสามารถรักษาทางแยกชุมชนสำหรับผู้มีส่วนร่วมโอเพ่นซอร์สได้ สิ่งเหล่านี้ไม่ได้เผยแพร่ไปยัง tensorflow.org