Рекомендации по работе с функциями и классами для Python

Ответ 1

Вы должны использовать reStructuredText и проверить конструкции разметки Sphinx. Все классные дети это делают.

Вы должны следовать соглашениям docstring. то есть.

Он предписывает функцию или метод эффект как команда ( "Сделайте это", "Вернуть это" ).

Вам следует избегать ненужного повторения или объяснения чрезвычайно очевидных. Пример того, что не делать:

def do_things(verbose=False):
    """Do some things.
    :param verbose: Be verbose (give additional messages).
    """
    raise NotImplementedError

Если бы вы хотели описать что-то неочевидное, это была бы другая история; например, эта подробная информация вызывает сообщения в потоке stdout или logging. Это не относится к Python, но следует из более ручных волновых идеалов, таких как самодокументирующий код и код/​​документация DRY.

Старайтесь избегать упоминания конкретных типов, если это возможно (абстрактные или интерфейсные типы обычно в порядке). Упомянутые протоколы обычно более полезны с точки зрения печати утки (т.е. "Итерируемый" вместо set, или "измененная упорядоченная последовательность" вместо list). Я видел некоторый код, который является очень буквальным и тяжелым WRT :rtype: и :type param: документацией на уровне функций, которая, как мне показалось, не согласуется с менталитетом утиной печати. ​​

Ответ 2

Как сказал Эмджи, Django - хороший проект для четких, последовательных руководств по стилю.

Например, их Contribute to Django style guide даже доходит до описания того, как они хотели бы видеть документацию. В частности, они упоминают:

В docstrings используйте "слова действия", например:

def foo():
    """
    Calculates something and returns the result.
    """
    pass

Вот пример того, что не делать:

def foo():
    """
    Calculate something and return the result.
    """
    pass

Ответ 3

Я думаю, что лучший ресурс будет Документирование Python

Цитата:

В этом документе описывается руководство по стилю для нашей документации, настраиваемая разметка reStructuredText, представленная для поддержки документации Python и того, как она должна использоваться, а также системы сборки Sphinx.

Sphinx: официальный генератор документации Python

Ответ 4

Лучший способ изучить методы документации - это, вероятно, посмотреть исходный код хорошо известного проекта. Как Djangoproject.

Ответ 5

Существует не менее 3 разных стилей: традиционная docstring, Google и NumPy. Первый из них довольно хорошо поддерживается такими инструментами, как PyCharm IDE и тем, что я обычно использую. Обратите внимание, что все 3 стиля поддерживают reStructuredText, который является расширенной уценкой, как показано ниже.

Традиционная docstring

Вот полный пример с часто используемыми элементами.

"""
.. module:: write your comments anywhere including classes
.. note:: you can use these elements anywhere   
.. moduleauthor:: My Name <[email protected]>
"""

def function1(self, arg1, arg2):
    """This is short explanation

    This is a longer explanation, with latex syntax :math:`\\alpha`.
    You can have many lines here.

    **Make this bold**:
     - Bullet point 1
     - Bullet point 2

    :param arg1: the first value
    :param arg2: the 2nd value
    :type arg1: int, float,...
    :returns: some value
    :rtype: int, float

    :Example:

    >>> import something
    >>> function1(0, 1.0)
    2

    .. note:: This will be in a box
    .. seealso:: :class:`MyOtherClass`
    .. warning:: This will be in red box
    .. todo:: this will be in orange box
    """
    return 0

Стиль Google

стиль Google более читабельен для пользователя и обычно также хорошо поддерживается с расширениями, такими как Napoleon.

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

Стиль NumPy

Стиль NumPy/SciPy очень похож на Google, но с другим (и более подробным) форматированием.

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

Как создать документацию

Чтобы завершить ответ, выполните быстрые шаги для создания файла документации из кода:

sudo pip install sphinx
sphinx-quickstart
cd docs
make html
open _build/html/index.html

Подробнее здесь