Tôi thích Doxygen để tạo tài liệu về mã C hoặc PHP. Tôi có một dự án Python sắp tới và tôi nghĩ rằng tôi nhớ rằng Python không có /* .. */nhận xét và cũng có cơ sở tự lập tài liệu riêng của nó, đây dường như là cách tuyệt vời để lập tài liệu.
Vì tôi đã quen với Doxygen, làm cách nào tôi có thể sử dụng nó để tạo tài liệu Python của mình? Có điều gì đặc biệt mà tôi cần biết không?
Câu trả lời:
Điều này được ghi lại trên trang web doxygen , nhưng để tóm tắt ở đây:
Bạn có thể sử dụng doxygen để ghi lại mã Python của mình. Bạn có thể sử dụng cú pháp chuỗi tài liệu Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
Trong trường hợp đó, các nhận xét sẽ được trích xuất bởi doxygen, nhưng bạn sẽ không thể sử dụng bất kỳ lệnh doxygen đặc biệt nào .
Hoặc bạn có thể (tương tự như các ngôn ngữ kiểu C trong doxygen) nhân đôi dấu nhận xét ( #) trên dòng đầu tiên trước thành viên:
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
Trong trường hợp đó, bạn có thể sử dụng các lệnh doxygen đặc biệt. Không có chế độ đầu ra Python cụ thể, nhưng bạn rõ ràng có thể cải thiện kết quả bằng cách đặt OPTMIZE_OUTPUT_JAVAthành YES.
Thành thật mà nói, tôi hơi ngạc nhiên về sự khác biệt - có vẻ như một khi doxygen có thể phát hiện các nhận xét trong khối ## hoặc khối "" ", hầu hết công việc sẽ được thực hiện và bạn có thể sử dụng các lệnh đặc biệt trong Cả hai trường hợp. Có thể họ mong đợi những người sử dụng "" "tuân thủ các thực hành tài liệu Pythonic nhiều hơn và điều đó sẽ ảnh hưởng đến các lệnh doxygen đặc biệt?
Bộ lọc đầu vào doxypy cho phép bạn sử dụng gần như tất cả các thẻ định dạng của Doxygen ở định dạng docstring Python tiêu chuẩn. Tôi sử dụng nó để ghi lại một khung ứng dụng trò chơi C ++ và Python hỗn hợp lớn và nó hoạt động tốt.
Cuối cùng, bạn chỉ có hai lựa chọn:
Bạn tạo nội dung của mình bằng Doxygen hoặc bạn tạo nội dung của mình bằng Sphinx *.
Doxygen : Nó không phải là công cụ được lựa chọn cho hầu hết các dự án Python. Nhưng nếu bạn phải xử lý các dự án liên quan khác được viết bằng C hoặc C ++ thì điều đó có thể có ý nghĩa. Đối với điều này, bạn có thể cải thiện sự tích hợp giữa Doxygen và Python bằng doxypypy .
Sphinx : Công cụ defacto để ghi lại một dự án Python. Bạn có ba tùy chọn ở đây: thủ công, bán tự động (tạo sơ khai) và hoàn toàn tự động (giống Doxygen).
autosummary_generatecấu hình. Bạn sẽ yêu cầu thiết lập một trang với tính năng tự động, sau đó chỉnh sửa các trang theo cách thủ công. Bạn có các tùy chọn, nhưng kinh nghiệm của tôi với cách tiếp cận này là nó đòi hỏi quá nhiều cấu hình và cuối cùng, ngay cả sau khi tạo các mẫu mới, tôi vẫn tìm thấy lỗi và không thể xác định chính xác cái gì được hiển thị là API công khai và cái gì không. Ý kiến của tôi là công cụ này tốt cho thế hệ sơ khai sẽ yêu cầu chỉnh sửa thủ công và không có gì hơn. Giống như một phím tắt để kết thúc trong thủ công.Có các tùy chọn khác cần lưu ý:
__all__biến explicite.
Sphinx chủ yếu là một công cụ để định dạng tài liệu được viết độc lập với mã nguồn, theo tôi hiểu.
Để tạo ra các tài liệu API từ docstrings Python, các công cụ hàng đầu là pdoc và pydoctor . Đây là tài liệu API do pydoctor tạo cho Twisted và Bazaar .
Tất nhiên, nếu bạn chỉ muốn xem các docstrings trong khi đang làm việc, có công cụ dòng lệnh " pydoc " và cũng như help()chức năng có sẵn trong trình thông dịch tương tác.
Một công cụ tài liệu rất tốt khác là nhân sư . Nó sẽ được sử dụng cho tài liệu python 2.6 sắp tới và được sử dụng bởi django và rất nhiều dự án python khác.
Từ trang web của nhân sư: