Làm cách nào tôi có thể liệt kê các thành viên không có giấy tờ với nhân sư/tự động?

Question

Tôi đang sử dụng nhân sư có phần mở rộng autodoc và muốn tạo một danh sách chỉ chứa các hàm thành viên không có giấy tờ trong một số mô-đun chứ không phải thành viên được tài liệu.

tôi thành công có thể tạo ra một danh sách bao gồm cả thành viên ghi nhận và các thành viên không có giấy tờ như sau:

.. automodule:: module 
    :members: 
    :undoc-members: 

Sử dụng :members: chỉ một mình tạo ra danh sách các thành viên chỉ ghi nhận, như mong đợi.

.. automodule:: module 
    :members: 

nhưng chỉ sử dụng chỉ thị :undoc-members: một mình (ví dụ bỏ qua :members: cờ) không dẫn đến bất kỳ danh sách ở tất cả:

.. automodule:: module 
    :undoc-members: 

Có cách nào để tự động tạo này?

(Tài liệu chính bao gồm trang hiển thị tất cả các thành viên được tài liệu, nhưng tôi thấy hữu ích hơn nhiều để đảm bảo rằng tôi đã viết tài liệu cho từng chức năng, v.v ... bằng một trang đơn liệt kê bất kỳ thành viên nào không có giấy tờ, không hiển thị văn bản cho những tài liệu được ghi lại).

Answer 1

Trọng sự kiện autodoc-process-docstring (như ghi nhận của @delnan) có thể giúp đỡ, bằng cách thêm dòng sau vào conf.py:

# set up the types of member to check that are documented 
members_to_watch = ['function',]; 

def warn_undocumented_members(app, what, name, obj, options, lines): 
    if(what in members_to_watch and len(lines)==0): 
     # warn to terminal during build 
     print "Warning: ", what, "is undocumented: ", name, "(%d)"% len(lines); 
     # or modify the docstring so the rendered output is highlights the omission 
     lines.append(".. Warning:: %s '%s' undocumented" % (what, name)); 

Và sau đó kết nối chức năng này để sự kiện này (từ một câu trả lời trong this SO thread):

def setup(app): 
    app.connect('autodoc-process-docstring', warn_undocumented_members); 

Để bật (tắt) các cảnh báo bao gồm (loại trừ) thành viên chưa hoàn thành - toàn cầu với autodoc_default_flags trong conf.py hoặc với cả chỉ thị như trong câu hỏi.

autodoc_default_flags = ['members', 'undoc-members' ] 
#autodoc_default_flags = ['members' ] 

EDIT:

Tôi đã cố gắng để mở rộng phương pháp này để tạo chỉ các thành viên undoc, theo phương pháp sau:

• có điều kiện thiết lập một tài sản, nói rằng, warn_undoc=True, trên đối tượng trong khi đang thực hiện chức năng warn_undocumented_members (ở trên)
• gắn chức năng ghi đè thứ hai vào sự kiện tiền xử lý autodoc-skip-member bỏ qua tất cả các thành viên nếu họ đã làm không có warn_undoc thiết lập.

Tuy nhiên, điều tra thêm quy định cách tiếp cận này, bởi vì autodoc-skip-member xảy ra cho mỗi nhóm thành viên trước khi xảy ra autodoc-process-docstring. Do đó, các thuộc tính được đặt quá muộn để bỏ qua điều kiện dựa trên sự hiện diện/vắng mặt của các tài liệu.