sphinx_napoleon_google_style_docstring_class_and_function_example.py

1# To use this, add 'sphinx.ext.napoleon' to your extensions list in conf.py
2
3def function_with_types_in_docstring(param1, param2):
4    """Example function with types documented in the docstring.
5
6    `PEP 484`_ type annotations should be preferred over documenting type hints
7    in docstrings.
8
9    Args:
10        param1 (int): The first parameter.
11        param2 (str): The second parameter.
12
13    Returns:
14        bool: The return value. True for success, False otherwise.
15
16    .. _PEP 484:
17        https://www.python.org/dev/peps/pep-0484/
18    """
19    return True
20
21class ExampleClass:
22    """The summary line for a class docstring should fit on one line.
23
24    If the class has public attributes, they may be documented here
25    in an ``Attributes`` section and follow the same formatting as a
26    function's ``Args`` section.
27
28    Attributes:
29        attr1 (str): Description of `attr1`.
30        attr2 (:obj:`int`, optional): Description of `attr2`.
31    """
32
33    def __init__(self, param1, param2, param3):
34        """Example of docstring on the __init__ method.
35
36        Args:
37            param1 (str): Description of `param1`.
38            param2 (:obj:`int`, optional): Description of `param2`. Defaults to 0.
39            param3 (list(str)): Description of `param3`.
40        """
41        self.attr1 = param1
42        self.attr2 = param2
43
44    def example_method(self, param1, param2):
45        """Class methods are similar to regular functions.
46
47        Args:
48            param1: The first parameter.
49            param2: The second parameter.
50
51        Returns:
52            bool: True if successful, False otherwise.
53        """
54        return True