คู่มือรูปแบบเอกสาร TensorFlow

แนวทางปฏิบัติที่ดีที่สุด

• มุ่งเน้นไปที่ความตั้งใจของผู้ใช้และผู้ชม
• ใช้คำศัพท์ในชีวิตประจำวันและทำให้ประโยคสั้นลง
• ใช้การสร้างประโยค การใช้ถ้อยคำ และการใช้อักษรตัวพิมพ์ใหญ่ที่สอดคล้องกัน
• ใช้ส่วนหัวและรายการเพื่อทำให้เอกสารของคุณสแกนได้ง่ายขึ้น
• คู่มือสไตล์เอกสารสำหรับนักพัฒนาซอฟต์แวร์ของ Google มีประโยชน์

มาร์กดาวน์

ด้วยข้อยกเว้นบางประการ TensorFlow ใช้ไวยากรณ์ Markdown ที่คล้ายกับ GitHub Flavoured Markdown (GFM) ส่วนนี้อธิบายความแตกต่างระหว่างไวยากรณ์ GFM Markdown และ Markdown ที่ใช้สำหรับเอกสาร TensorFlow

เขียนเกี่ยวกับโค้ด

การกล่าวถึงโค้ดแบบอินไลน์

ใส่ `backticks` ไว้รอบสัญลักษณ์ต่อไปนี้เมื่อใช้ในข้อความ:

• ชื่ออาร์กิวเมนต์: `input` , `x` , `tensor`
• ชื่อเทนเซอร์ที่ส่งคืน: `output` , `idx` , `out`
• ประเภทข้อมูล: `int32` , `float` , `uint8`
• ชื่อปฏิบัติการอื่นๆ อ้างอิงในข้อความ: `list_diff()` , `shuffle()`
• ชื่อคลาส: `tf.Tensor` , `Strategy`
• ชื่อไฟล์: `image_ops.py` , `/path_to_dir/file_name`
• นิพจน์หรือเงื่อนไขทางคณิตศาสตร์: `-1-input.dims() <= dim <= input.dims()`

บล็อกรหัส

ใช้ backticks สามอันเพื่อเปิดและปิดบล็อคโค้ด ทางเลือก ระบุภาษาการเขียนโปรแกรมหลังกลุ่ม backtick แรก เช่น:

```python
# some python code here
```

ลิงก์ใน Markdown และสมุดบันทึก

ลิงก์ระหว่างไฟล์ในที่เก็บ

ใช้ลิงก์ที่เกี่ยวข้องระหว่างไฟล์ในที่เก็บ GitHub เดียว รวมนามสกุลไฟล์.

ตัวอย่างเช่น ไฟล์ที่คุณกำลังอ่านนี้ มาจากที่เก็บ https://github.com/tensorflow/docs ดังนั้นจึงสามารถใช้พาธสัมพัทธ์เพื่อลิงก์ไปยังไฟล์อื่นในพื้นที่เก็บข้อมูลเดียวกันได้ดังนี้:

• [Basics](../../guide/basics.ipynb) สร้าง Basics

นี่เป็นแนวทางที่แนะนำเนื่องจากวิธีนี้ทำให้ลิงก์บน tensorflow.org , GitHub และ Colab ทำงานได้ทั้งหมด นอกจากนี้ผู้อ่านยังอยู่ในไซต์เดียวกันเมื่อคลิกลิงก์

ลิงค์ภายนอก

สำหรับลิงก์ไปยังไฟล์ที่ไม่ได้อยู่ในที่เก็บปัจจุบัน ให้ใช้ลิงก์ Markdown มาตรฐานที่มี URI แบบเต็ม ต้องการลิงก์ไปยัง tensorflow.org URI หากมี

หากต้องการลิงก์ไปยังซอร์สโค้ด ให้ใช้ลิงก์ที่ขึ้นต้นด้วย https://www.github.com/tensorflow/tensorflow/blob/master/ ตามด้วยชื่อไฟล์ที่เริ่มต้นที่รูท GitHub

เมื่อทำการลิงก์ออกจาก tensorflow.org ให้ใส่ `` ไว้ในลิงก์ Markdown เพื่อให้สัญลักษณ์ "ลิงก์ภายนอก" ปรากฏขึ้น

• [GitHub](https://github.com/tensorflow/docs) สร้าง GitHub

อย่ารวมพารามิเตอร์การค้นหา URI ในลิงก์:

• ใช้: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
• ไม่ใช่: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

รูปภาพ

คำแนะนำในส่วนก่อนหน้ามีไว้สำหรับลิงก์ไปยังหน้าต่างๆ รูปภาพได้รับการจัดการที่แตกต่างกัน

โดยทั่วไป คุณไม่ควรตรวจสอบรูปภาพ แต่ให้เพิ่ม ทีม TensorFlow-Docs ใน PR ของคุณแทน และขอให้พวกเขาโฮสต์รูปภาพบน tensorflow.org ซึ่งจะช่วยลดขนาดของพื้นที่เก็บข้อมูลของคุณ

หากคุณส่งรูปภาพไปยังที่เก็บของคุณ โปรดทราบว่าบางระบบไม่จัดการเส้นทางสัมพันธ์ไปยังรูปภาพ ต้องการใช้ URL แบบเต็มซึ่งชี้ไปยังตำแหน่งสุดท้ายของรูปภาพบน tensorflow.org

ลิงก์ไปยังเอกสารประกอบ API

ลิงก์ API จะถูกแปลงเมื่อมีการเผยแพร่ไซต์ หากต้องการลิงก์ไปยังหน้าอ้างอิง API ของสัญลักษณ์ ให้ใส่เส้นทางสัญลักษณ์ไว้ใน backticks:

• `tf.data.Dataset` สร้าง tf.data.Dataset

แนะนำให้ใช้เส้นทางแบบเต็มเล็กน้อย ยกเว้นเส้นทางยาว เส้นทางสามารถย่อได้โดยการปล่อยส่วนประกอบเส้นทางนำ เส้นทางบางส่วนจะถูกแปลงเป็นลิงก์หาก:

• มีอย่างน้อยหนึ่ง . ในเส้นทางและ
• เส้นทางบางส่วนไม่ซ้ำกันภายในโครงการ

เส้นทาง API เชื่อมโยงกัน สำหรับทุกโครงการ ด้วย Python API ที่เผยแพร่บน tensorflow.org คุณสามารถลิงก์ไปยังหลายโครงการย่อยได้อย่างง่ายดายจากไฟล์เดียวโดยล้อมชื่อ API ด้วย backticks ตัวอย่างเช่น:

• `tf.metrics` , `tf_agents.metrics` , `text.metrics` ทำให้เกิด: tf.metrics , tf_agents.metrics , text.metrics

สำหรับสัญลักษณ์ที่มีนามแฝงหลายเส้นทาง มีการตั้งค่าเล็กน้อยสำหรับเส้นทางที่ตรงกับหน้า API บน tensorflow.org นามแฝงทั้งหมดจะเปลี่ยนเส้นทางไปยังหน้าที่ถูกต้อง

คณิตศาสตร์ในมาร์กดาวน์

คุณสามารถใช้ MathJax ภายใน TensorFlow เมื่อแก้ไขไฟล์ Markdown แต่โปรดทราบสิ่งต่อไปนี้:

• MathJax แสดงผลอย่างถูกต้องบน tensorflow.org
• MathJax แสดงผลไม่ถูกต้องบน GitHub
• สัญกรณ์นี้อาจไม่เหมาะสมสำหรับนักพัฒนาที่ไม่คุ้นเคย
• เพื่อความสอดคล้อง tensorflow.org จะต้องปฏิบัติตามกฎเดียวกันกับ Jupyter/Colab

ใช้ $$ รอบบล็อกของ MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

ตัดนิพจน์ MathJax แบบอินไลน์ด้วย $ ... $ :

This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

นี่คือตัวอย่างของนิพจน์ MathJax แบบอินไลน์: \( 2 \times 2 = 4 \)

\\( ... \\) ตัวคั่นยังใช้ได้กับคณิตศาสตร์แบบอินไลน์ แต่บางครั้งรูปแบบ $ ก็อ่านง่ายกว่า

สไตล์ร้อยแก้ว

หากคุณกำลังจะเขียนหรือแก้ไขส่วนสำคัญของเอกสารประกอบคำบรรยาย โปรดอ่าน คู่มือสไตล์เอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ Google

หลักการของสไตล์ที่ดี

• ตรวจสอบการสะกดและไวยากรณ์ในการร่วมให้ข้อมูลของคุณ โปรแกรมแก้ไขส่วนใหญ่มีเครื่องตรวจตัวสะกดหรือมีปลั๊กอินตรวจสอบตัวสะกดที่พร้อมใช้งาน คุณยังสามารถวางข้อความของคุณลงใน Google เอกสารหรือซอฟต์แวร์เอกสารอื่นๆ เพื่อการตรวจสอบการสะกดและไวยากรณ์ที่มีประสิทธิภาพยิ่งขึ้น
• ใช้น้ำเสียงที่เป็นกันเองและเป็นกันเอง เขียนเอกสาร TensorFlow เช่นการสนทนา ราวกับว่าคุณกำลังพูดคุยกับบุคคลอื่นแบบตัวต่อตัว ใช้น้ำเสียงสนับสนุนในบทความ

• หลีกเลี่ยงการปฏิเสธความรับผิดชอบ ความคิดเห็น และการตัดสินคุณค่า คำว่า "ง่าย" "แค่" และ "เรียบง่าย" เต็มไปด้วยข้อสันนิษฐาน บางสิ่งอาจดูง่ายสำหรับคุณ แต่อาจยากสำหรับอีกคนหนึ่ง พยายามหลีกเลี่ยงสิ่งเหล่านี้ทุกครั้งที่เป็นไปได้
• ใช้ประโยคง่ายๆ ตรงประเด็น โดยไม่มีศัพท์เฉพาะที่ซับซ้อน ประโยคความประกอบ ประโยคต่อเนื่องกัน และสำนวนเฉพาะสถานที่สามารถทำให้ข้อความเข้าใจและแปลได้ยาก หากประโยคสามารถแบ่งออกเป็นสองประโยคได้ก็น่าจะควร หลีกเลี่ยงอัฒภาค ใช้รายการหัวข้อย่อยตามความเหมาะสม
• ให้บริบท อย่าใช้คำย่อโดยไม่อธิบาย อย่าพูดถึงโปรเจ็กต์ที่ไม่ใช่ TensorFlow โดยไม่ลิงก์กับโปรเจ็กต์เหล่านั้น อธิบายว่าเหตุใดจึงเขียนโค้ดในลักษณะที่เป็นอยู่

คู่มือการใช้งาน

ปฏิบัติการ

ในไฟล์มาร์กดาวน์ ให้ใช้ # ⇒ แทนเครื่องหมายเท่ากับตัวเดียว เมื่อคุณต้องการแสดงว่า op ส่งคืนอะไร

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

ในสมุดบันทึก ให้แสดงผลลัพธ์แทนการเพิ่มความคิดเห็น (หากไม่ได้กำหนดนิพจน์สุดท้ายในเซลล์สมุดบันทึกให้กับตัวแปร นิพจน์นั้นจะแสดงโดยอัตโนมัติ)

ในเอกสารอ้างอิง API ต้องการใช้ doctest เพื่อแสดงผลลัพธ์

เทนเซอร์

เมื่อคุณพูดถึงเทนเซอร์โดยทั่วไป อย่าใช้คำว่า tensor เป็นตัวพิมพ์ใหญ่ เมื่อคุณกำลังพูดถึงวัตถุเฉพาะที่มอบให้หรือส่งคืนจาก op คุณควรใช้คำว่า Tensor ให้เป็นตัวพิมพ์ใหญ่และเพิ่ม backticks รอบๆ เนื่องจากคุณกำลังพูดถึงวัตถุ Tensor

อย่าใช้คำว่า Tensors (พหูพจน์) เพื่ออธิบายวัตถุ Tensor หลายรายการ เว้นแต่ว่าคุณกำลังพูดถึงวัตถุ Tensors จริงๆ ให้พูดว่า "รายการ (หรือคอลเลกชัน) ของวัตถุ Tensor " แทน

ใช้คำว่า รูปร่าง เพื่อแสดงรายละเอียดแกนของเทนเซอร์ และแสดงรูปร่างในวงเล็บเหลี่ยมพร้อมเครื่องหมายย้อนกลับ ตัวอย่างเช่น:

If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

ดังที่กล่าวข้างต้น แนะนำให้ใช้ "แกน" หรือ "ดัชนี" มากกว่า "มิติ" เมื่อพูดถึงองค์ประกอบของรูปร่างของ Tensor มิฉะนั้น อาจทำให้เกิดความสับสนระหว่าง "มิติ" กับมิติของปริภูมิเวกเตอร์ได้ง่าย "เวกเตอร์สามมิติ" มีแกนเดียวยาว 3