Chủ yếu là vấn đề lịch sử, nhưng cũng là câu hỏi về sở thích cá nhân (và dự án). Những ngày này, bạn có thể nhận được tài liệu khá có thể sử dụng bằng cách dựa chủ yếu vào docstrings và sau đó có thể thêm văn xuôi xung quanh họ.
Tài liệu của CPython tuy nhiên, từ trước sự tồn tại của Sphinx (trên thực tế, Georg Brandl đã viết phiên bản Sphinx ban đầu để thay thế hệ thống tài liệu cũ của CPython).
Vì vậy, như một vấn đề về chính sách, tài liệu và tài liệu văn xuôi vẫn được duy trì riêng mà không dựa vào việc sử dụng autodoc.
Chúng tôi cũng không cho phép sử dụng tài liệu reStucturedText trong thư viện chuẩn làm giảm thêm lợi ích của việc sử dụng tự động sửa. (Xem Q 10 trong PEP 287 Q & A: http://www.python.org/dev/peps/pep-0287/#questions-answers)
Cuối cùng, Georg Brandl pointed out rằng CPython là ở một vị trí khá độc đáo mà bạn cần phải cẩn thận để đảm bảo rằng phiên bản của thư viện chuẩn được cung cấp docstrings khi Sphinx chạy là chính xác giống như bạn đang tạo tài liệu cho. Nó sẽ là quá dễ dàng để vô tình đưa vào phiên bản sai, cũng như tạo ra một sự phụ thuộc mạnh mẽ giữa việc xây dựng một Python làm việc và có thể tái tạo tài liệu. Trên mặt autodoc, bạn có vấn đề là khi chỉnh sửa tài liệu dựa trên autodoc, bạn không thể dễ dàng nhìn thấy nội dung docstring nội tuyến, do đó, nó có thể khó khăn để đảm bảo văn bản docstring và văn xuôi bổ sung cũng đọc cùng với nhau. Vấn đề đó có thể được giảm nhẹ thông qua giải pháp làm mới trình duyệt tự động như http://pymolurus.blogspot.com.au/2012/01/documentation-viewer-for-sphinx.html
autodoc cũng có vấn đề với phụ thuộc vào việc xây dựng lại, vì nó không tự động thêm phụ thuộc đúng vào tệp nguồn Python. Tôi chắc chắn đã có vấn đề mà docstrings đã thay đổi nhưng Sphinx đã không tái tạo các tập tin đầu ra có liên quan. (Tôi không tin rằng điều này đã được sửa chữa, nhưng nếu nó đã được giải quyết trong các bản phát hành Sphinx gần đây thì hãy cho tôi biết trong phần bình luận và tôi sẽ loại bỏ quan sát này).
Mặc dù tôi nghĩ bạn có tài liệu tốt hơn và tài liệu tốt hơn bằng cách duy trì chúng một cách riêng biệt (vì hai kiểu viết không chính xác giống nhau và docstrings thô thường dễ đọc hơn là văn bản thuần túy hơn khi được đánh dấu reStructuredText), đó là một cách tiếp cận với chi phí khá cao trong nỗ lực bảo trì bổ sung và tăng nguy cơ không thống nhất.
Theo đó, đối với hầu hết các dự án Python bên thứ ba, lời khuyên của tôi sẽ thực sự là để tránh theo gương các thư viện chuẩn và thay vì:
- docstrings sử dụng reRestructuredText (xem PEP 287: http://www.python.org/dev/peps/pep-0287/)
- sử dụng apidoc/autodoc
- thêm tài liệu văn xuôi bổ sung xung quanh docstrings được nhúng tự động thay vì thay thế
- sử dụng phương pháp tự động sửa lỗi như vậy như liên kết ở trên để xem như thế nào docstrings đọc như một phần của tài liệu
Trong khi nó không phải là một giải pháp hoàn hảo, phương pháp này không tiết kiệm khá nhiều nỗ lực trùng lặp trong việc giữ cả docstrings và tài liệu văn xuôi lên đến ngày.
cảm ơn bạn đã giải thích này. Cá nhân tôi không nghĩ, rằng docstrings thô dễ đọc hơn như văn bản thuần túy, đặc biệt là khi sử dụng 'numpydoc' https://raw.github.com/numpy/numpy/master/doc/EXAMPLE_DOCSTRING.rst.txt. Vì vậy, tôi sẽ tiếp tục sử dụng autodoc. – bmu