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

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

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

มาร์คดาวน์

โดยส่วนใหญ่แล้ว TensorFlow ใช้ไวยากรณ์ Markdown ที่คล้ายกับ GitHub Flavored Markdown (GFM) ส่วนนี้จะอธิบายความแตกต่างระหว่างไวยากรณ์ Markdown ของ GFM กับ 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()`

บล็อกโค้ด

ใช้เครื่องหมายแบ็กติ๊กสามตัวเพื่อเปิดและปิดบล็อกโค้ด คุณสามารถระบุภาษาโปรแกรมหลังกลุ่มแบ็กติ๊กกลุ่มแรกได้ (ถ้าต้องการ) ตัวอย่างเช่น:

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

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

การเชื่อมโยงระหว่างไฟล์ในที่เก็บข้อมูล

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

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

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

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

ลิงก์ภายนอก

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

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

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

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

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

• อ้างอิงจาก: https://www.tensorflow.org/guide/data
• หมายเหตุ: https://www.tensorflow.org/guide/data?hl=en

รูปภาพ

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

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

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

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

ลิงก์ API จะถูกแปลงเมื่อเว็บไซต์ได้รับการเผยแพร่ หากต้องการเชื่อมโยงไปยังหน้าอ้างอิง API ของสัญลักษณ์ ให้ใส่เส้นทางของสัญลักษณ์ไว้ในเครื่องหมายแบ็กติ๊ก (`)

• `tf.data.Dataset` จะสร้าง tf.data.Dataset ขึ้นมา

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

• มีจุดอย่างน้อยหนึ่ง . ในเส้นทาง และ
• เส้นทางบางส่วนนี้เป็นเอกลักษณ์เฉพาะในโครงการนี้

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

• `tf.metrics` , `tf_agents.metrics` , `text.metrics` จะสร้างผลลัพธ์เป็น: tf.metrics , tf_agents.metrics , text.metrics .

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

คณิตศาสตร์ใน Markdown

คุณสามารถใช้ 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 Docs หรือโปรแกรมเอกสารอื่นๆ เพื่อตรวจสอบการสะกดและไวยากรณ์อย่างละเอียดมากขึ้นได้
• ใช้ภาษาที่เป็นกันเองและเป็นมิตร เขียนเอกสาร TensorFlow เหมือนกับการสนทนา—ราวกับว่าคุณกำลังพูดคุยกับอีกคนแบบตัวต่อตัว ใช้โทนเสียงที่ให้กำลังใจในบทความ

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

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

ฝ่ายปฏิบัติการ

ในไฟล์ Markdown ให้ใช้ # ⇒ แทนเครื่องหมายเท่ากับตัวเดียวเมื่อต้องการแสดงค่าที่ส่งคืนจากโอเปอเรเตอร์

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

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

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

เทนเซอร์

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

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

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

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