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

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

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

Markdown

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

เขียนเกี่ยวกับรหัส

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

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

• ชื่ออาร์กิวเมนต์: `input` , `x` x` , `tensor`
• ส่งคืนชื่อเทนเซอร์: `output` , `idx` , `out`
• ประเภทข้อมูล: `int32` `float` `uint8`
• การอ้างอิงชื่อ op อื่น ๆ ในข้อความ: `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) สร้าง ข้อมูลพื้นฐาน

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

ลิงค์ภายนอก

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

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

เมื่อทำการเชื่อมโยงออกจาก tensorflow.org ให้ใส่ {:.external} ในลิงก์ Markdown เพื่อให้แสดงสัญลักษณ์ "external link"

• [GitHub](https://github.com/tensorflow/docs){:.external} สร้าง 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 ในการประชาสัมพันธ์ของคุณแทน และขอให้พวกเขาโฮสต์รูปภาพบน tensorflow.org วิธีนี้ช่วยลดขนาดพื้นที่เก็บข้อมูลของคุณ

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

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

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

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

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

• มีอย่างน้อยหนึ่ง . ในเส้นทางและ
• พาธบางส่วนไม่ซ้ำกันภายในโปรเจ็กต์

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

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

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

Ops

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

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

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

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

เทนเซอร์

เมื่อพูดถึงเทนเซอร์โดยทั่วไป อย่าใช้คำว่า เทนเซอร์ เป็นตัวพิมพ์ใหญ่ เมื่อพูดถึงออบเจกต์เฉพาะที่มีให้หรือส่งคืนจาก 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