Używam sphinx i wtyczki autodoc do generowania dokumentacji API dla moich modułów Pythona. Chociaż mogę zobaczyć, jak ładnie udokumentować określone parametry, nie mogę znaleźć przykładu, jak udokumentować **kwargs
parametr.
Czy ktoś ma dobry przykład jasnego sposobu ich udokumentowania?
Odpowiedzi:
Myślę, że
subprocess
dokumentacja -module jest dobrym przykładem. Podaj wyczerpującą listę wszystkich parametrów dla klasy nadrzędnej / nadrzędnej . Następnie odnieś się do tej listy dla wszystkich innych wystąpień**kwargs
.źródło
subprocess.call(*popenargs, **kwargs)
. Udokumentowano, żesubprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
wszystko po tym*
jest rozpoznawanymi kluczami**kwargs
(lub przynajmniej tymi często używanymi)subprocess.Popen
i nie jestem pewien, czy jest to już szczególnie wspaniały przykład.Po znalezieniu tego pytania zdecydowałem się na następujący, który jest prawidłowym Sfinksem i działa dość dobrze:
Wymagane
r"""..."""
jest, aby uczynić to „surowym” dokumentem, a tym samym zachować\*
nienaruszony (aby Sphinx odebrał jako dosłowne,*
a nie początek „podkreślenia”).Wybrane formatowanie (lista wypunktowana z typem w nawiasach i opisem oddzielonym m-myślnikami) ma po prostu pasować do automatycznego formatowania zapewnianego przez Sphinx.
Po wykonaniu tych starań, aby sekcja „Argumenty słów kluczowych” wyglądała jak domyślna sekcja „Parametry”, wydaje się, że może być łatwiejsze wprowadzenie własnej sekcji parametrów od samego początku (jak w przypadku niektórych innych odpowiedzi) , ale jako dowód słuszności koncepcji jest to jeden ze sposobów na uzyskanie ładnego wyglądu uzupełniającego,
**kwargs
jeśli już używasz Sphinx.źródło
Dokumenty w stylu Google przeanalizowane przez Sphinx
Zastrzeżenie: nie testowano.
Z tego wycięcia w przykładzie z dokumentacją sfinksa ,
*args
i**kwargs
pozostają nierozwinięte :Ja proponuję następujące rozwiązanie dla zwartości:
Zwróć uwagę, jak
Optional
nie jest wymagane w przypadku**key
argumentów.W przeciwnym razie możesz spróbować jawnie wymienić argumenty * pod
Other Parameters
i**kwargs
podKeyword Args
(zobacz przeanalizowane sekcje ):źródło
W ich dokumentacji znajduje się przykładowy dokument dotyczący Sphinx. W szczególności przedstawiają następujące:
Chociaż pytałeś o sfinkswyraźnie wskazałbym również na przewodnik Google Python Style Guide . Ich przykładowy dokument wydaje się sugerować, że nie odwołują się one konkretnie do kwargs. (other_silly_variable = Brak)
ABB ma pytanie o akceptowaną odpowiedź dotyczącą odniesienia do dokumentacji zarządzania podprocesem. Jeśli importujesz moduł, możesz szybko wyświetlić dokumentację modułu za pośrednictwem inspect.getsource.
Przykład z interpretera Pythona korzystającego z rekomendacji Silent Ghost:
Oczywiście możesz również przeglądać dokumentację modułu za pomocą funkcji pomocy. Na przykład pomoc (podproces)
Osobiście nie jestem fanem podprocesu docstring dla kwargs jako przykładu, ale podobnie jak przykład Google nie wyświetla osobno kwargów, jak pokazano w przykładzie dokumentacji Sphinx.
Dołączam tę odpowiedź na pytanie ABB, ponieważ warto zauważyć, że w ten sposób możesz przejrzeć źródła lub dokumentację dowolnego modułu, aby uzyskać wgląd i inspirację do komentowania swojego kodu.
źródło
other_silly_variable
nie jest argumentem kwargs, ale całkowicie normalnym.Jeśli ktoś szuka poprawnej składni… Oto przykładowy ciąg dokumentów. Tak właśnie to zrobiłem, mam nadzieję, że jest to przydatne dla Ciebie, ale nie mogę twierdzić, że jest zgodne z niczym szczególnym.
źródło
Zależy to od stylu używanej dokumentacji, ale jeśli używasz stylu numpydoc , zaleca się dokumentowanie
**kwargs
za pomocąOther Parameters
.Na przykład, idąc za przykładem Quorniana:
Zwróć szczególną uwagę, że zalecane jest podanie wartości domyślnych kwargs, ponieważ nie są one oczywiste z sygnatury funkcji.
źródło
Jeśli szukasz, jak to zrobić w stylu numpydoc , możesz po prostu wspomnieć
**kwargs
w sekcji Parametry bez określania typu - jak pokazano na przykładzie numpydoc z rozszerzenia sphinx napolean i przewodnika docstring z dokumentacji pandy sprint 2018.Oto przykład znalazłem z przewodnikiem programisty Godzina ostatniej który bardzo dobrze wyjaśnia, co powinno być opis z
**kwargs
parametrem:Alternatywnie, opierając się na tym, co zasugerował @Jonas Adler, uważam, że lepiej jest umieścić
**kwargs
opis i jego opis wOther Parameters
sekcji - nawet ten przykład z przewodnika dokumentacji matplotlib sugeruje to samo.źródło