Widziałem kilka różnych stylów pisania dokumentów w Pythonie, czy istnieje styl oficjalny lub „uzgodniony”?

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 Epytextformacie) do generowania dokumentacji.

Przykład:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- 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:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- 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:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

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.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

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

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:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Chciałbym to rozszerzyć, aby zawierało także informacje o typie w argumentach, jak opisano w tym samouczku dokumentacji Sphinx . Na przykład:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

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:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Nad:

def sq(n):
    """Returns the square of n."""
    return n * n

I zwykle pomijam komentowanie pierwszego wiersza dłuższych dokumentów:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

To znaczy, uważam, że dokumenty, które zaczynają się tak, są niechlujne.

def sq(n):
    """Return the squared result. 
    ...

Jak zapewne nikt o tym nie wspomniał: możesz także użyć Numpy Docstring Standard . Jest szeroko stosowany w środowisku naukowym.

• Specyfikację formatu z numpy razem z np
• Masz do renderowania rozszerzenie sfinksa: numpydoc
• I przykład tego, jak pięknie może wyglądać renderowany dokument: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

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:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 jest oficjalnym standardem kodowania python. Zawiera sekcję dotyczącą dokumentów, która odnosi się do PEP-257 - kompletnej specyfikacji dokumentów.

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.

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.