มีส่วนร่วมในเอกสารประกอบ TensorFlow API

เอกสารที่ทดสอบได้

TensorFlow ใช้ DocTest เพื่อทดสอบข้อมูลโค้ดในเอกสาร Python ข้อมูลโค้ดต้องเป็นโค้ด Python ที่เรียกใช้งานได้ หากต้องการเปิดใช้งานการทดสอบ ให้เติม >>> (วงเล็บมุมซ้ายสามวงเล็บ) ตัวอย่างเช่น นี่เป็นข้อความที่ตัดตอนมาจากฟังก์ชัน tf.concat ในไฟล์ต้นฉบับ array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

ในการประเมินคุณภาพเอกสารอ้างอิง โปรดดูที่ส่วนตัวอย่างของ คำแนะนำเอกสาร TensorFlow 2 API (โปรดทราบว่า Task Tracker ในแผ่นงานนี้ไม่ได้ใช้งานแล้ว)

ทำให้โค้ดทดสอบได้ด้วย DocTest

ปัจจุบัน เอกสารประกอบจำนวนมากใช้ backticks (```) เพื่อระบุรหัส ในการทำให้โค้ดทดสอบได้ด้วย DocTest:

• ลบ backticks (```) และใช้วงเล็บด้านซ้าย (>>>) ที่ด้านหน้าของแต่ละบรรทัด ใช้ (...) นำหน้าบรรทัดต่อ
• เพิ่มบรรทัดใหม่เพื่อแยกข้อมูลโค้ด DocTest ออกจากข้อความ Markdown เพื่อให้แสดงผลอย่างถูกต้องบน tensorflow.org

การปรับแต่ง

TensorFlow ใช้การปรับแต่งบางอย่างกับตรรกะ doctest ในตัว:

• ไม่ได้เปรียบเทียบค่า float เป็นข้อความ: ค่า float ถูกดึงออกมาจากข้อความและเปรียบเทียบโดยใช้ allclose กับ liberal atol และ rtol tolerences สิ่งนี้ช่วยให้:
  • เอกสารที่ชัดเจนยิ่งขึ้น - ผู้เขียนไม่จำเป็นต้องรวมตำแหน่งทศนิยมทั้งหมด
  • การทดสอบที่มีประสิทธิภาพยิ่งขึ้น - การเปลี่ยนแปลงเชิงตัวเลขในการใช้งานพื้นฐานไม่ควรทำให้ doctest ล้มเหลว
• จะตรวจสอบผลลัพธ์ก็ต่อเมื่อผู้เขียนรวมเอาท์พุตสำหรับบรรทัด ซึ่งช่วยให้เอกสารมีความชัดเจนมากขึ้น เนื่องจากโดยปกติผู้เขียนไม่จำเป็นต้องบันทึกค่ากลางที่ไม่เกี่ยวข้องเพื่อป้องกันไม่ให้พิมพ์

ข้อควรพิจารณาเกี่ยวกับ Docstring

• โดยรวม : เป้าหมายของ doctest คือการจัดเตรียมเอกสารและยืนยันว่าเอกสารใช้งานได้ ซึ่งแตกต่างจากการทดสอบหน่วย ดังนั้น:
  • เก็บตัวอย่างง่ายๆ
  • หลีกเลี่ยงผลลัพธ์ที่ยาวหรือซับซ้อน
  • ใช้ตัวเลขกลมถ้าเป็นไปได้
• รูปแบบเอาต์พุต : เอาต์พุตของข้อมูลโค้ดต้องอยู่ใต้โค้ดที่สร้างเอาต์พุตโดยตรง นอกจากนี้ ผลลัพธ์ใน docstring จะต้องเท่ากับผลลัพธ์ที่ได้หลังจากรันโค้ด ดูตัวอย่างด้านบน ตรวจสอบ ส่วนนี้ ในเอกสารประกอบ DocTest หากเอาต์พุตเกินขีดจำกัด 80 บรรทัด คุณสามารถใส่เอาต์พุตพิเศษในบรรทัดใหม่ แล้ว DocTest จะรับรู้ ตัวอย่างเช่น ดูบล็อกหลายบรรทัดด้านล่าง
• Globals : `tf` , np และ os มีอยู่ใน DocTest ของ TensorFlow เสมอ

• ใช้สัญลักษณ์ : ใน DocTest คุณสามารถเข้าถึงสัญลักษณ์ที่กำหนดไว้ในไฟล์เดียวกันได้โดยตรง หากต้องการใช้สัญลักษณ์ที่ไม่ได้กำหนดไว้ในไฟล์ปัจจุบัน โปรดใช้ API สาธารณะของ tf.xxx แทน xxx ดังที่คุณเห็นในตัวอย่างด้านล่าง `random.normal` เข้าถึงได้ผ่าน `tf.random.normal` นี่เป็นเพราะว่า `random.normal` ไม่ปรากฏใน NewLayer

  def NewLayer():
    """This layer does cool stuff.
  
    Example usage:
  
    >>> x = tf.random.normal((1, 28, 28, 3))
    >>> new_layer = NewLayer(x)
    >>> new_layer
    <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
    """
  

• ค่า จุดทศนิยม : TensorFlow doctest แยกค่าทศนิยมจากสตริงผลลัพธ์ และเปรียบเทียบโดยใช้ np.allclose ด้วยความคลาดเคลื่อนที่สมเหตุสมผล ( atol=1e-6 , rtol=1e-6 ) วิธีนี้ผู้เขียนไม่จำเป็นต้องกังวลเกี่ยวกับเอกสารประกอบที่แม่นยำเกินไปซึ่งทำให้เกิดความล้มเหลวเนื่องจากปัญหาด้านตัวเลข เพียงวางค่าที่ต้องการ

• เอาต์พุตที่ไม่ได้กำหนดไว้ : ใช้จุดไข่ปลา ( ... ) สำหรับส่วนที่ไม่แน่นอนและ DocTest จะละเว้นสตริงย่อยนั้น

  x = tf.random.normal((1,))
  print(x)
      <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>
      
  

• บล็อกหลายบรรทัด : DocTest เข้มงวดเกี่ยวกับความแตกต่างระหว่างคำสั่งเดียวและหลายบรรทัด สังเกตการใช้ (...) ด้านล่าง:

  if x > 0:
    print("X is positive")
  model.compile(
    loss="mse",
    optimizer="adam")
      
  

• ข้อยกเว้น : รายละเอียดข้อยกเว้นจะถูกละเว้น ยกเว้นข้อยกเว้นที่ยกขึ้น ดู สิ่งนี้ สำหรับรายละเอียดเพิ่มเติม

  np_var = np.array([1, 2])
  tf.keras.backend.is_keras_tensor(np_var)
      Traceback (most recent call last):
  
      ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.
      
  

ใช้สำเนาของ tf-doctest ในโครงการ

API บางตัวใน TensorFlow มาจากโครงการภายนอก:

• tf.estimator (จาก tensorflow_estimator )
• tf.summary เซอร์บอร์ด )
• tf.keras.preprocessing (จาก keras-preprocessing )

หากคุณกำลังทำงานในโปรเจ็กต์ภายนอก หรือบน TensorFlow API ที่อยู่ในโปรเจ็กต์ภายนอก คำแนะนำเหล่านี้จะไม่ทำงานเว้นแต่โปรเจ็กต์นั้นจะมีสำเนา tf_doctest ในเครื่องเป็นของตัวเอง และคุณใช้สำเนานั้นแทน TensorFlow

ตัวอย่างเช่น: tf_estimator_doctest.py

ทดสอบกับเครื่องในพื้นที่ของคุณ

มีสองวิธีในการทดสอบโค้ดใน docstring ในเครื่อง:

• หากคุณกำลังเปลี่ยนเฉพาะ docstring ของ class/function/method คุณสามารถทดสอบได้โดยส่งเส้นทางของไฟล์นั้นไปที่ tf_doctest.py ตัวอย่างเช่น:

  python tf_doctest.py --file=<file_path>
  

  การดำเนินการนี้จะเรียกใช้โดยใช้ TensorFlow เวอร์ชันที่คุณติดตั้งไว้ เพื่อให้แน่ใจว่าคุณกำลังใช้รหัสเดียวกับที่คุณกำลังทดสอบ:

  • ใช้การติดตั้ง pip tf- nightly ล่าสุด pip install -U tf-nightly
  • รีเบสคำขอดึงของคุณไปยังการดึงล่าสุดจากสาขาหลัก ของ TensorFlow

• หากคุณกำลังเปลี่ยนรหัสและ docstring ของ class/function/method คุณจะต้อง สร้าง TensorFlow จาก source เมื่อคุณตั้งค่าให้สร้างจากแหล่งที่มาแล้ว คุณสามารถเรียกใช้การทดสอบได้:

  bazel run //tensorflow/tools/docs:tf_doctest
  

  หรือ

  bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
  

  --module สัมพันธ์กับ tensorflow.python