Widziałem kilka różnych stylów pisania dokumentów w Pythonie, czy istnieje styl oficjalny lub „uzgodniony”?
python
coding-style
documentation
docstring
Noah McIlraith
źródło
źródło
epydoc
,doxygen
,sphinx
? Czy ktoś ma jakieś statystyki, to jedna z nich zastąpi inne, w takich przypadkach zbyt wiele opcji może zaszkodzić.def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""
Odpowiedzi:
Formaty
Dokumenty w języku Python można pisać w kilku formatach, jak pokazały inne posty. Jednak domyślny format tekstowy Sphinx nie został wymieniony i jest oparty na reStructuredText (reST) . Informacje o głównych formatach można znaleźć w tym poście na blogu .
Zauważ, że reST jest zalecany przez PEP 287
Poniżej podano najczęściej używane formaty dokumentów.
- Epitext
Historycznie dominował styl podobny do javadoc , więc został on przyjęty jako podstawa dla Epydoc (w tak zwanym
Epytext
formacie) do generowania dokumentacji.Przykład:
- reszta
Obecnie prawdopodobnie bardziej rozpowszechnionym formatem jest format reStructuredText (reST), który jest używany przez Sphinx do generowania dokumentacji. Uwaga: jest domyślnie używany w JetBrains PyCharm (wpisz potrójne cudzysłowy po zdefiniowaniu metody i wciśnij Enter). Jest również domyślnie używany jako format wyjściowy w płatności.
Przykład:
- Google
Google ma własny format, który jest często używany. Może być również interpretowany przez Sphinx (tj. Przy użyciu wtyczki Napoleon ).
Przykład:
Jeszcze więcej przykładów
- Numpydoc
Pamiętaj, że Numpy zaleca stosowanie własnego numpydoc opartego na formacie Google i używanego przez Sphinx.
Konwertowanie / generowanie
Możliwe jest użycie narzędzia, takiego jak Pyment, do automatycznego generowania dokumentów do projektu w języku Python, który nie został jeszcze udokumentowany, lub do konwersji istniejących dokumentów (z możliwością mieszania kilku formatów) z jednego formatu na inny.
Uwaga: przykłady pochodzą z dokumentacji płatności
źródło
Przewodnik po stylu Google zawiera doskonały przewodnik po stylu Python. Zawiera konwencje czytelnej składni dokumentów, która oferuje lepsze wskazówki niż PEP-257. Na przykład:
Chciałbym to rozszerzyć, aby zawierało także informacje o typie w argumentach, jak opisano w tym samouczku dokumentacji Sphinx . Na przykład:
źródło
Konwencje docstring są w PEP-257 ze znacznie większą szczegółowością niż PEP-8.
Dokumenty wydają się jednak znacznie bardziej osobiste niż inne obszary kodu. Różne projekty będą miały swój własny standard.
Zazwyczaj zawsze dołączam dokumenty, ponieważ pokazują one, jak korzystać z funkcji i co robi bardzo szybko.
Wolę zachować spójność, niezależnie od długości łańcucha. Lubię kodować, kiedy wcięcia i odstępy są spójne. Oznacza to, że używam:
Nad:
I zwykle pomijam komentowanie pierwszego wiersza dłuższych dokumentów:
To znaczy, uważam, że dokumenty, które zaczynają się tak, są niechlujne.
źródło
"""Return the squared result"""
raczej niż"""Returns the squared result"""
. Chociaż osobiście piszę moje, jak tu są Tim, pomimo tego, co mówi PEP.Jak zapewne nikt o tym nie wspomniał: możesz także użyć Numpy Docstring Standard . Jest szeroko stosowany w środowisku naukowym.
Rozszerzenie Sfinks Napolean do analizowania dokumentów w stylu Google (zalecane w odpowiedzi na @Nathan) obsługuje również dokumenty w stylu Numpy i dokonuje krótkiego porównania obu.
I na koniec podstawowy przykład, aby dać wyobrażenie o tym, jak to wygląda:
źródło
PEP-8 jest oficjalnym standardem kodowania python. Zawiera sekcję dotyczącą dokumentów, która odnosi się do PEP-257 - kompletnej specyfikacji dokumentów.
źródło
To jest Python; wszystko idzie . Zastanów się, jak opublikować swoją dokumentację . Ciągi znaków są niewidoczne, z wyjątkiem czytników Twojego kodu źródłowego.
Ludzie naprawdę lubią przeglądać i przeszukiwać dokumentację w Internecie. Aby to osiągnąć, użyj narzędzia do dokumentacji Sphinx . Jest to de facto standard dokumentowania projektów w języku Python. Produkt jest piękny - spójrz na https://python-guide.readthedocs.org/en/latest/ . Witryna Read the Docs udostępni darmowe dokumenty.
źródło
ipython
do testowania biblioteki, a to sprawia, że czytanie dokumentów jest bardzo proste - wszystko co muszę napisać toyour_module.some_method_im_curious_about?
dostaję każdy ładny wydruk, w tym dokumentację.help
funkcję na udokumentowanej funkcji / metodzie / klasie (i możesz to zrobić, nawet jeśli masz dostęp tylko do skompilowanego modułu). Osobiście uważam, że należy o tym pamiętać przy wyborze konwencji docstringowej (tzn. Że zamierza się ją czytać taką, jaka jest).Sugeruję użycie programu pep257 Python Vladimira Kelesheva do sprawdzania twoich dokumentów w PEP-257 i Numpy Docstring Standard do opisywania parametrów, zwrotów itp.
pep257 zgłosi rozbieżność, którą zrobisz ze standardu i nazywa się jak pylint i pep8.
źródło
pydocstyle --select=D4 tmp.py
sprawdza szereg problemów z treścią dokumentów, w tym nazywanie sekcji.