เขียน Document ใน Airflow โดยใช้ doc_md

Photo by Sigmund on Unsplash

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

สำหรับชาว Pythonista แล้ว การใช้ Python Docstring ก็เป็นวิธีหนึ่งที่เราจะสามารถเขียน Document ของเราลงไปในโค้ดได้เลย

แต่อย่างไรก็ดี สำหรับแฟนๆ Airflow อย่างพวกเรา การเอา Docstring มาเขียนอธิบาย Task ก็อาจจะพอได้อยู่ และจะดีกว่าถ้าเราใช้ Documentation ของ Airflow ไปเลย ซึ่งสิ่งที่เราเขียนลงไป มันจะไปแสดงผลบน Web ในหน้า Graph View, Tree View และ Calendar View สำหรับ DAGs และหน้า Task Instance Details สำหรับ Task ด้วยนะ! 🤩

อยากลองแล้วใช่ไหม? ตามไปดูโค้ด DAG ตัวอย่างด้านล่างนี้กันเลย 🔥

สังเกตบรรทัดล่างสุดครับ ผมใช้แบบนี้

dag.doc_md = __doc__

ตรงนี้หมายความว่าให้ DAG ของเราไปใช้ Docstring ที่ผมเขียนไว้ด้านบนสุดของไฟล์นี้ ผลที่ได้คือ

ที่หน้า Tree View มี DAG Docs โผล่ขึ้นมา (หน้า Graph View และ Calendar View ก็จะมี DAG Docs เช่นกัน)

เราสามารถเขียน Document ให้กับ Task ได้เช่นกัน ตามนี้ (บรรทัดที่ 21 ในโค้ด)

start.doc_md = """
This task is a starting point. It will show on the Task Instance Details.
"""

ซึ่ง Document ตรงนี้จะไปแสดงผลในหน้า Task Instance Details.. ผมเดาว่าหลายๆ คนอาจจะไม่รู้จักหน้านี้ 😂 อ่ะ วิธีเข้าไปหน้านี้ก็ จากรูปด้านบนให้เรากดที่ Task Instance (สีเขียวๆ) อันไหนก็ได้ครับ แล้วเราจะเห็นเป็นหน้า Modal แบบนี้ขึ้นมา

หน้า Task Instance ที่เป็น Modal แสดงผลขึ้นมา

จากนั้นให้เรากดที่ปุ่ม Instance Details ครับ เราก็จะเข้าไปที่หน้า Task Instance Details แล้ว

หน้า Task Instance Details

แล้วเราก็จะเห็น Document ที่เราเขียนไว้สำหรับ Task นี้ครับผม 😊

สุดท้ายแล้ว อยากบอกว่า Document เป็นสิ่งที่จริงๆ แล้วจำเป็นนะ เรามักจะนึกถึงมันเป็นอันดับต้นๆ เลย ตอนที่เรามีปัญหา แต่ส่วนใหญ่เราจะนึกถึงมันเป็นอันดับสุดท้ายตอนที่เราลงมือเขียนโค้ด..

หาโอกาส หรือพยายามหาทางเพิ่มโอกาสในเขียน Document กันนะครับ เขียนเพื่อตัวเราในอนาคต ในวันที่เราย้อนกลับมาอ่าน 😉

ปล. ถ้าใครเขียน doc_md ใส่ตรง Task แล้วไม่ขึ้น ลองเช็คเวอร์ชั่นของ Airflow ดูครับ เพราะว่าเวอร์ชั่นก่อนหน้า 2.0.2 จะมีบั๊กอยู่

Reference

• https://atsushihara.medium.com/encouragement-of-airflow-doc-md-3da7fa80ec6b