122 lines
3.5 KiB
Python
122 lines
3.5 KiB
Python
"""This is the docstring for the example.py module. Modules names should
|
|
have short, all-lowercase names. The module name may have underscores if
|
|
this improves readability.
|
|
|
|
Every module should have a docstring at the very top of the file. The
|
|
module's docstring may extend over multiple lines. If your docstring does
|
|
extend over multiple lines, the closing three quotation marks must be on
|
|
a line by itself, preferably preceded by a blank line.
|
|
|
|
"""
|
|
import os # standard library imports first
|
|
|
|
# Do NOT import using *, e.g. from numpy import *
|
|
#
|
|
# Import the module using
|
|
#
|
|
# import numpy
|
|
#
|
|
# instead or import individual functions as needed, e.g
|
|
#
|
|
# from numpy import array, zeros
|
|
#
|
|
# If you prefer the use of abbreviated module names, we suggest the
|
|
# convention used by NumPy itself::
|
|
|
|
import numpy as np
|
|
import matplotlib as mpl
|
|
import matplotlib.pyplot as plt
|
|
|
|
# These abbreviated names are not to be used in docstrings; users must
|
|
# be able to paste and execute docstrings after importing only the
|
|
# numpy module itself, unabbreviated.
|
|
|
|
from my_module import my_func, other_func
|
|
|
|
def foo(var1, var2, long_var_name='hi'):
|
|
r"""A one-line summary that does not use variable names or the
|
|
function name.
|
|
|
|
Several sentences providing an extended description. Refer to
|
|
variables using back-ticks, e.g. `var`.
|
|
|
|
Parameters
|
|
----------
|
|
var1 : array_like
|
|
Array_like means all those objects -- lists, nested lists, etc. --
|
|
that can be converted to an array. We can also refer to
|
|
variables like `var1`.
|
|
var2 : int
|
|
The type above can either refer to an actual Python type
|
|
(e.g. ``int``), or describe the type of the variable in more
|
|
detail, e.g. ``(N,) ndarray`` or ``array_like``.
|
|
long_var_name : {'hi', 'ho'}, optional
|
|
Choices in brackets, default first when optional.
|
|
|
|
Returns
|
|
-------
|
|
type
|
|
Explanation of anonymous return value of type ``type``.
|
|
describe : type
|
|
Explanation of return value named `describe`.
|
|
out : type
|
|
Explanation of `out`.
|
|
|
|
Other Parameters
|
|
----------------
|
|
only_seldom_used_keywords : type
|
|
Explanation
|
|
common_parameters_listed_above : type
|
|
Explanation
|
|
|
|
Raises
|
|
------
|
|
BadException
|
|
Because you shouldn't have done that.
|
|
|
|
See Also
|
|
--------
|
|
otherfunc : relationship (optional)
|
|
newfunc : Relationship (optional), which could be fairly long, in which
|
|
case the line wraps here.
|
|
thirdfunc, fourthfunc, fifthfunc
|
|
|
|
Notes
|
|
-----
|
|
Notes about the implementation algorithm (if needed).
|
|
|
|
This can have multiple paragraphs.
|
|
|
|
You may include some math:
|
|
|
|
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
|
|
|
|
And even use a greek symbol like :math:`omega` inline.
|
|
|
|
References
|
|
----------
|
|
Cite the relevant literature, e.g. [1]_. You may also cite these
|
|
references in the notes section above.
|
|
|
|
.. [1] O. McNoleg, "The integration of GIS, remote sensing,
|
|
expert systems and adaptive co-kriging for environmental habitat
|
|
modelling of the Highland Haggis using object-oriented, fuzzy-logic
|
|
and neural-network techniques," Computers & Geosciences, vol. 22,
|
|
pp. 585-588, 1996.
|
|
|
|
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]
|
|
>>> print("a\n\nb")
|
|
a
|
|
b
|
|
|
|
"""
|
|
|
|
pass
|