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