มา Document สำหรับ Class Module ใน Python เพื่อใช้งานในทีมกัน ด้วย pdoc

หลายท่าน น่าจะเคยเจอปัญหา ในการต้องมาอธิบายให้เพื่อนร่วมทีมฟัง ถึงวิธีใช้งาน บาง Function หรือ Class Module ที่เราหรือเพื่อนร่วมทีมเขียน Code ไว้ แม้บางครั้งเราจะเขียน String Doc (__doc__ หรือ docstring) ใน Python ไว้แล้วก็ตาม ดังภาพตัวอย่างด้านบน

ก็มักจะเจอปัญหา เพื่อนร่วมทีมยังหาวิธีใช้งานยาก หรือไม่รู้ว่ามี Function หรือ Class นั้นๆอยู่ หรือเจอปัญหา เมื่อมีเพื่อร่วมทีม เข้ามาใหม่ ก็ต้องมานั่งอธิบาย วิธีใช้งานกันเป็นวันๆ หรือ 2-3 วันเลยทีเดี่ยว ซึ่งเอาจริงๆแล้ว สิ่งที่เราอธิบายไปนั้น แน่นอนว่า เพื่อนร่วมทีมเรา มักจะจำกันไม่ค่อยได้

จะดีกว่าไหม ถ้าเรามี HTML Document แบบนี้

https://back-dev-docs.web.app/

เอาละมาเริ่มกันแบบจริงจังชักที สมุดว่าเรามี โครงสร้าง โปรเจ็คประมาณนี้

.
└── project/
├── docs/
│ ├── …
│ ├── index.html
│ └── …
├── shared_library_python/
│ └── python/
│ ├── …
│ ├── Connection.py
│ ├── CRUDModel.py
│ ├── EnvModel.py
│ └── …
└── document.py

และมีเขียน String Doc (__doc__ หรือ docstring) ใน Python ไว้แล้ว ดังภาพ

เราจะสามารถใช้ Code ต่อไปนี้ในการสร้าง HTML Document ได้ทันที

pip install pdoc

#!/usr/bin/env python

import glob
import json
import os
from datetime import datetime

vvvvv = datetime.now().strftime('%Y-%m-%d')
"""
Generate the code documentation, using pydoc.
"""

docs_folder = f"docs_{vvvvv}"
ignored_files = ["MongoDBEngine.py"]
module_list = []
for dirname in ['shared_library_python/python/']:
    flist = glob.glob(f'{dirname}/*.py')
    for fname in flist:
        if '__init__' not in fname and fname not in ignored_files and "EX_" not in fname:
            module_list.append(fname)
            bname = os.path.splitext(os.path.basename(fname))[0].lower()


    os.system(f'python3.8 -m pdoc -d google -o {docs_folder} -e module={json.dumps(module_list)}')

ตัวอย่าง การเขียน String Doc (__doc__ หรือ docstring) ใน Python

ลองสร้างไฟล์ demo.py และใส่ Code ด้านล่างลงไป จากนั้น เรียกใช้คำสั่งต่อไปนี้ดูครับ

pdoc demo.py

ไฟล์ demo.py

"""
A small `pdoc` example.
"""

class Dog:
    """🐕"""
    name: str
    """The name of our dog."""
    friends: list["Dog"]
    """The friends of our dog."""

    def __init__(self, name: str):
        """Make a Dog without any friends (yet)."""
        self.name = name
        self.friends = []

    def bark(self, loud: bool = True):
        """*woof*"""

ดูการใช้งานเพิ่มเติมได้ที่เว็บไชต์

https://pdoc.dev/