1"""This is the docstring for the example.py module.  Modules names should
2have short, all-lowercase names.  The module name may have underscores if
3this improves readability.
4
5Every module should have a docstring at the very top of the file.  The
6module's docstring may extend over multiple lines.  If your docstring does
7extend over multiple lines, the closing three quotation marks must be on
8a line by itself, preferably preceded by a blank line.
9
10"""
11import os # standard library imports first
12
13# Do NOT import using *, e.g. from numpy import *
14#
15# Import the module using
16#
17#   import numpy
18#
19# instead or import individual functions as needed, e.g
20#
21#  from numpy import array, zeros
22#
23# If you prefer the use of abbreviated module names, we suggest the
24# convention used by NumPy itself::
25
26import numpy as np
27import matplotlib as mpl
28import matplotlib.pyplot as plt
29
30# These abbreviated names are not to be used in docstrings; users must
31# be able to paste and execute docstrings after importing only the
32# numpy module itself, unabbreviated.
33
34from my_module import my_func, other_func
35
36def foo(var1, var2, long_var_name='hi'):
37    r"""A one-line summary that does not use variable names or the
38    function name.
39
40    Several sentences providing an extended description. Refer to
41    variables using back-ticks, e.g. `var`.
42
43    Parameters
44    ----------
45    var1 : array_like
46        Array_like means all those objects -- lists, nested lists, etc. --
47        that can be converted to an array.  We can also refer to
48        variables like `var1`.
49    var2 : int
50        The type above can either refer to an actual Python type
51        (e.g. ``int``), or describe the type of the variable in more
52        detail, e.g. ``(N,) ndarray`` or ``array_like``.
53    long_var_name : {'hi', 'ho'}, optional
54        Choices in brackets, default first when optional.
55
56    Returns
57    -------
58    type
59        Explanation of anonymous return value of type ``type``.
60    describe : type
61        Explanation of return value named `describe`.
62    out : type
63        Explanation of `out`.
64
65    Other Parameters
66    ----------------
67    only_seldom_used_keywords : type
68        Explanation
69    common_parameters_listed_above : type
70        Explanation
71
72    Raises
73    ------
74    BadException
75        Because you shouldn't have done that.
76
77    See Also
78    --------
79    otherfunc : relationship (optional)
80    newfunc : Relationship (optional), which could be fairly long, in which
81              case the line wraps here.
82    thirdfunc, fourthfunc, fifthfunc
83
84    Notes
85    -----
86    Notes about the implementation algorithm (if needed).
87
88    This can have multiple paragraphs.
89
90    You may include some math:
91
92    .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
93
94    And even use a greek symbol like :math:`omega` inline.
95
96    References
97    ----------
98    Cite the relevant literature, e.g. [1]_.  You may also cite these
99    references in the notes section above.
100
101    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
102       expert systems and adaptive co-kriging for environmental habitat
103       modelling of the Highland Haggis using object-oriented, fuzzy-logic
104       and neural-network techniques," Computers & Geosciences, vol. 22,
105       pp. 585-588, 1996.
106
107    Examples
108    --------
109    These are written in doctest format, and should illustrate how to
110    use the function.
111
112    >>> a = [1, 2, 3]
113    >>> print([x + 3 for x in a])
114    [4, 5, 6]
115    >>> print("a\n\nb")
116    a
117    b
118
119    """
120
121    pass
122