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