Jak działa "autodoc_default_flags" w konfiguracji python Sphinx?

Question

Próbuję wygenerować dokumentację dla moich klas python wykorzystujących Sphinx 1,4 i sphinx-apidoc i rozszerzenie sphinx.ext.autodoc.

Mam wiele modułów i chcę, aby każdy wyświetlał tylko nazwy klas, ale nie pełną listę metod w klasie (które wszystkie mają docstrukcje w moim kodzie).

Oto urywek z mojego pliku conf.py:

sys.path.insert(0, '/blah/sphinx/src') 

extensions = ['sphinx.ext.autodoc'] 
autodoc_member_order = 'bysource' 
autodoc_default_flags = ['no-members'] 

Oto moduł zabawka (my_module.py), które używam, aby dowiedzieć się, jak Sphinx działa:

""" 
============== 
Test my module 
============== 
""" 

def module_function(): 
    """Here is a module function, let's see if it's in""" 
    print 'module level' 

class TestClass: 
    """ 
    Test this class 

    Here is some more class documentation. 
    """ 
    def __init__(self): 
     """Here is init""" 
     self.test = True 

    def getName(self, inputName): 
     """Summary for getName 

     more documentation for getName 
     """  
     print "hello" 
     return inputName 

jestem pokazuję tylko kod tej klasy, na wypadek, gdyby było coś, co muszę robić w ciągach dokumentów, których mi brakuje.

biegnę sfinks-apidoc do generowania RST pliki:

sfinks-apidoc -f -M -e -o docs// bla/sfinks/src/

następnie zbudować:

uczynić html

I nie może być jasne, o co autodoc_default_flags należy robić. Pomyślałem, że kiedy uruchomiłeś sfinks-apidoc z tymi ustawionymi flagami, te flagi zostały zastosowane do dyrektyw w plikach .rst. Jednak po biegnę sfinks-apidoc, otrzymuję ten .rst plik:

my_module module 
===================== 

.. automodule:: my_module 
    :members: 
    :undoc-members: 
    :show-inheritance: 

bym nie oczekiwany :members: być stosowane ze względu na ustawienie te flagi, ale nie jest! Na stronie html dostępne są metody wraz z ich dokumentami.

FWIW, autodoc_member_order działa; Mogę ustawić, aby zmienić kolejność metod.

więc moje pytania:

1. Czy autodoc_default_flags robić co opisałem albo ja to nieporozumienie?
2. Jeśli można go automatycznie ukryć członków z kompilacji, czy używam go poprawnie? Jeśli tak, to wszelkie myśli o tym, dlaczego nadal otrzymuję :members: dodane do plików .rst?
3. Jeśli nie rozumiem tego, to co tak naprawdę robi? I jak mogę automatycznie ukryć metodę docstring metody z mojej kompilacji?

Idealnie chcę coś scipy ma na przykład tutaj:

http://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html

Do tego gram około z Napoleonem i sphinx.ext.autosummary rozszerzeń, ale wydaje się, że apidoc sam powinien być w stanie ukryć dokumentację metody klasy.

Answer 1

Myślałam, że kiedy zabrakło sfinks-apidoc z tymi flagami Ustaw, a następnie te flagi zostały zastosowane do dyrektyw w .rst plików.

sphinx-build ma zastosowanie autodoc_default_flags w conf.py, chyba że flagi są zastępowane w plikach * .rst.

sphinx-apidoc nie używa conf.py.

---

Jest możliwe, aby dostosować flagi w plikach * .rst generowanych przez Sfinks-apidoc poprzez zmienną środowiskową na SPHINX_APIDOC_OPTIONS (nie jest to wyjaśnione w dokumentacji Sfinks). Przykład:

$ export SPHINX_APIDOC_OPTIONS=no-members 
$ sphinx-apidoc -o docs/ /blah/sphinx/src/ 

To spowoduje automodule dyrektyw, które wyglądają tak:

.. automodule:: my_module 
    :no-members: 

Jeśli potrzebujesz większą kontrolę nad generowanym wyjściu, można chyba napisać własną wersję modułu apidoc.py . Zobacz Customize templates for `sphinx-apidoc`.