หลายท่าน น่าจะเคยเจอปัญหา ในการต้องมาอธิบายให้เพื่อนร่วมทีมฟัง ถึงวิธีใช้งาน บาง 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/