Jak mogę wyświetlić listę nieudokumentowanych członków za pomocą Sphinx/Autodoc?

Question

Używam sfinksa z rozszerzeniem autodoc, i chcę wygenerować listę tylko zawierającą nieudokumentowane funkcje członkowskie w kilku modułach, a nie udokumentowane elementy.

mogę z powodzeniem utworzyć listę, która zawiera oba udokumentowane i nieudokumentowane członkowie członków w następujący sposób:

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

Korzystanie dyrektywę :members: sam tworzy listę tylko udokumentowanych członków, zgodnie z oczekiwaniami.

.. automodule:: module 
    :members: 

ale używając tylko dyrektywę :undoc-members: samodzielnie (tj pomijając flagę :members:) nie powoduje żadnej liście w ogóle:

.. automodule:: module 
    :undoc-members: 

Czy istnieje sposób, aby automatycznie wygenerować to?

(Podstawowa dokumentacja zawiera stronę zawierającą wszystkich udokumentowanych członków, ale uważam, że o wiele bardziej przydatna jest opcja, w której mam napisane dokumenty dla każdej funkcji itp., Dzięki jednej stronie zawierającej listę nieudokumentowanych członków, bez pokazywania tekst dla tych, które są udokumentowane).

Answer 1

Zastępowanie zdarzenie autodoc-process-docstring (jak zauważył @delnan) może pomóc poprzez dodanie następujących do 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)); 

A następnie połączyć tę funkcję do zdarzenia (z odpowiedzią w this SO thread):

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

Aby włączyć (wyłączyć) ostrzeżenia obejmują (wykluczyć) to undoc członkami - globalnie autodoc_default_flags w conf.py lub obiema dyrektywami jak w pytaniu.

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

EDIT:

próbowałem przedłużyć ten podejście do generowania tylko członków undoc, w następujący sposób:

• warunkowo ustawić właściwość, powiedzmy, warn_undoc=True, na obiekt podczas funkcji warn_undocumented_members (powyżej)
• dołącza drugą funkcję nadpisywania do zdarzenia preprocesora autodoc-skip-member, które pominęły wszystkie elementy, jeśli zostały , a nie mają zestaw .

jednak dalsze śledztwo rządzi się to podejście, ponieważ autodoc-skip-member występuje dla każdej grupy użytkowników przed autodoc-process-docstring występuje. W związku z tym właściwości są ustawione zbyt późno, aby warunkowo pominąć na podstawie obecności/braku docstrukcji.