pydoc --- Trình tạo tài liệu và hệ thống trợ giúp trực tuyến¶
Source code: Lib/pydoc.py
Mô-đun pydoc tự động tạo tài liệu từ các mô-đun Python. Tài liệu có thể được trình bày dưới dạng các trang văn bản trên bảng điều khiển, được cung cấp cho trình duyệt web hoặc được lưu vào tệp HTML.
Đối với các mô-đun, lớp, hàm và phương thức, tài liệu được hiển thị được lấy từ chuỗi doc (tức là thuộc tính __doc__) của đối tượng và đệ quy các thành viên có thể ghi lại của nó. Nếu không có chuỗi tài liệu, pydoc sẽ cố gắng lấy mô tả từ khối dòng nhận xét ngay phía trên định nghĩa của lớp, hàm hoặc phương thức trong tệp nguồn hoặc ở đầu mô-đun (xem inspect.getcomments()).
Hàm tích hợp help() gọi hệ thống trợ giúp trực tuyến trong trình thông dịch tương tác, sử dụng pydoc để tạo tài liệu dưới dạng văn bản trên bảng điều khiển. Tài liệu văn bản tương tự cũng có thể được xem từ bên ngoài trình thông dịch Python bằng cách chạy pydoc dưới dạng tập lệnh tại dấu nhắc lệnh của hệ điều hành. Ví dụ: đang chạy
python -m pydoc sys
tại dấu nhắc shell sẽ hiển thị tài liệu trên mô-đun sys, theo kiểu tương tự như các trang hướng dẫn được hiển thị bằng lệnh Unix man. Đối số của pydoc có thể là tên của hàm, mô-đun hoặc gói hoặc tham chiếu chấm đến lớp, phương thức hoặc hàm trong mô-đun hoặc mô-đun trong gói. Nếu đối số của pydoc trông giống như một đường dẫn (nghĩa là nó chứa dấu phân cách đường dẫn cho hệ điều hành của bạn, chẳng hạn như dấu gạch chéo trong Unix) và tham chiếu đến tệp nguồn Python hiện có thì tài liệu sẽ được tạo cho tệp đó.
Ghi chú
Để tìm các đối tượng và tài liệu của chúng, pydoc nhập (các) mô-đun cần ghi lại. Do đó, bất kỳ mã nào ở cấp mô-đun sẽ được thực thi trong trường hợp đó. Sử dụng trình bảo vệ if __name__ == '__main__': để chỉ thực thi mã khi tệp được gọi dưới dạng tập lệnh chứ không chỉ được nhập.
Khi in đầu ra ra bảng điều khiển, pydoc cố gắng phân trang đầu ra để dễ đọc hơn. Nếu biến môi trường MANPAGER hoặc PAGER được đặt, pydoc sẽ sử dụng giá trị của nó làm chương trình phân trang. Khi cả hai được thiết lập, MANPAGER sẽ được sử dụng.
Việc chỉ định cờ -w trước đối số sẽ khiến tài liệu HTML được ghi vào một tệp trong thư mục hiện tại, thay vì hiển thị văn bản trên bảng điều khiển.
Việc chỉ định cờ -k trước đối số sẽ tìm kiếm các dòng tóm tắt của tất cả các mô-đun có sẵn cho từ khóa được cung cấp làm đối số, một lần nữa theo cách tương tự như lệnh Unix man. Dòng tóm tắt của một mô-đun là dòng đầu tiên trong chuỗi tài liệu của nó.
Bạn cũng có thể sử dụng pydoc để khởi động máy chủ HTTP trên máy cục bộ sẽ cung cấp tài liệu cho các trình duyệt web đang truy cập. python -m pydoc -p 1234 sẽ khởi động máy chủ HTTP trên cổng 1234, cho phép bạn duyệt tài liệu tại http://localhost:1234/ trong trình duyệt web ưa thích của bạn. Chỉ định 0 làm số cổng sẽ chọn một cổng tùy ý không được sử dụng.
python -m pydoc -n <hostname> sẽ khởi động máy chủ lắng nghe tên máy chủ đã cho. Theo mặc định, tên máy chủ là 'localhost' nhưng nếu bạn muốn máy chủ có thể truy cập được từ các máy khác, bạn có thể muốn thay đổi tên máy chủ mà máy chủ phản hồi. Trong quá trình phát triển, điều này đặc biệt hữu ích nếu bạn muốn chạy pydoc từ bên trong vùng chứa.
python -m pydoc -b sẽ khởi động máy chủ và mở thêm trình duyệt web tới trang chỉ mục mô-đun. Mỗi trang được cung cấp có một thanh điều hướng ở trên cùng, nơi bạn có thể trợ giúp Get về một mục riêng lẻ, Search tất cả các mô-đun có từ khóa trong dòng tóm tắt của chúng và đi tới các trang Module index, Topics và Keywords.
Khi pydoc tạo tài liệu, nó sử dụng môi trường và đường dẫn hiện tại để định vị các mô-đun. Do đó, việc gọi tài liệu pydoc spam chính xác là phiên bản của mô-đun mà bạn sẽ nhận được nếu khởi động trình thông dịch Python và gõ import spam.
Tài liệu mô-đun cho các mô-đun lõi được giả định nằm trong https://python.go-mizu.dev/X.Y/library/ trong đó X và Y là số phiên bản chính và phụ của trình thông dịch Python. Điều này có thể được ghi đè bằng cách đặt biến môi trường PYTHONDOCS thành một URL khác hoặc vào một thư mục cục bộ chứa các trang Hướng dẫn tham khảo Thư viện.
Thay đổi trong phiên bản 3.2: Đã thêm tùy chọn -b.
Thay đổi trong phiên bản 3.3: Tùy chọn dòng lệnh -g đã bị xóa.
Thay đổi trong phiên bản 3.4: pydoc hiện sử dụng inspect.signature() thay vì inspect.getfullargspec() để trích xuất thông tin chữ ký từ các lệnh gọi được.
Thay đổi trong phiên bản 3.7: Đã thêm tùy chọn -n.