คู่มือรูปแบบเอกสาร 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
```

ใช้ลิงก์ที่เกี่ยวข้องระหว่างไฟล์ในที่เก็บ 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 ของสัญลักษณ์ ให้ใส่เส้นทางสัญลักษณ์ไว้ใน backticks:

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

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

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

สำหรับสัญลักษณ์ที่มีนามแฝงหลายเส้นทาง มีการตั้งค่าเล็กน้อยสำหรับเส้นทางที่ตรงกับหน้า 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