Sphinx domyślnie nie generuje dokumentów dla __init __ (self). Próbowałem następujących rzeczy:
.. automodule:: mymodule
:members:
i
..autoclass:: MyClass
:members:
W conf.py ustawienie następujących elementów tylko dołącza __init __ (self) docstring do klasy docstring ( dokumentacja Sphinx autodoc wydaje się zgadzać, że jest to oczekiwane zachowanie, ale nie wspomina o problemie, który próbuję rozwiązać):
autoclass_content = 'both'
python
python-sphinx
autodoc
Jacob Marble
źródło
źródło
"both" Both the class’ and the __init__ method’s docstring are concatenated and inserted.
-> Dlatego powinna to być nie tylko dokumentacja__init__(self)
, ale także dokumentacja klasowa, jeśli to masz. Czy możesz podać przypadek testowy, ponieważ jeśli tak jest, wygląda to jak błąd, prawda?Odpowiedzi:
Oto trzy alternatywy:
Aby upewnić się, że
__init__()
jest to zawsze udokumentowane, możesz użyćautodoc-skip-member
w conf.py. Lubię to:To wyraźnie określa, że
__init__
nie należy go pomijać (co jest domyślne). Ta konfiguracja jest określana raz i nie wymaga żadnych dodatkowych znaczników dla każdej klasy w źródle .rst.special-members
Opcja została dodana w Sfinksa 1.1 . To sprawia, że "specjalni" członkowie (ci o takich nazwach__special__
) są dokumentowani przez autodoc.Od Sphinx 1.2 ta opcja przyjmuje argumenty, co czyni ją bardziej użyteczną niż poprzednio.
Zastosowanie
automethod
:Należy to dodać dla każdej klasy (nie można tego używać z
automodule
, jak wskazano w komentarzu do pierwszej wersji tej odpowiedzi).źródło
special-members
działa dobrze przy użyciuautomodule
. Używaj:special-members: __init__
tylko do dokumentowania__init__
.Byłeś blisko. Możesz skorzystać z
autoclass_content
opcji w swoimconf.py
pliku:źródło
autoclass_content = 'both'
opcję, która udokumentowała metodę init , ale spowodowała dwukrotne wyświetlenie autopodsumowania.W ciągu ostatnich lat pisałem kilka wariantów
autodoc-skip-member
wywołań zwrotnych dla różnych niepowiązanych projektów Pythona, ponieważ chciałem metody podoba__init__()
,__enter__()
i__exit__()
aby pokazać się w moim dokumentacji API (wszak te „specjalne” metody są częścią API i co lepsze miejsce do udokumentować je niż wewnątrz dokumentacji metody specjalnej).Niedawno zrobiłem najlepszą implementację i uczyniłem ją częścią jednego z moich projektów w Pythonie ( tutaj jest dokumentacja ). Wdrożenie w zasadzie sprowadza się do tego:
Tak, jest więcej dokumentacji niż logiki :-). Zaletą zdefiniowania takiego
autodoc-skip-member
wywołania zwrotnego nad użyciemspecial-members
opcji (dla mnie) jest to, żespecial-members
opcja umożliwia również dokumentację właściwości, takich jak__weakref__
(dostępne we wszystkich klasach nowego stylu, AFAIK), które uważam za szum i w ogóle nie są przydatne. Metoda wywołania zwrotnego unika tego (ponieważ działa tylko na funkcjach / metodach i ignoruje inne atrybuty).źródło
setup(app)
, aby została wykonana przez Sphinx.__init__
metoda ma niepusty ciąg znaków. Czy to?Mimo, że jest to starszy post, dla tych, którzy go teraz szukają, pojawiło się również inne rozwiązanie wprowadzone w wersji 1.8. Zgodnie z dokumentacją możesz dodać
special-member
klucz w opcji autodoc_default_options do plikuconf.py
.Przykład:
źródło
To jest wariant, który obejmuje tylko
__init__
wtedy, gdy ma argumenty:źródło