1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
# -*- coding: utf-8 -*-
"""Test Module for sphinx_rtd_theme."""
class Foo:
"""Docstring for class Foo.
This text tests for the formatting of docstrings generated from output
``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the
``<dl>``, and ``<dt>`` tags. Also, ``<tt>`` is used for class, method names
and etc, but those will *always* have the ``.descname`` or
``.descclassname`` class.
Term
It is also possible to include definitions inside docstrings.
They should be styled as a normal definition list.
:Field List:
It is also possible to include definitions inside docstrings.
They should be styled as a normal definition list.
.. [1] A footnote contains body elements, consistently indented by at
least 3 spaces.
.. [Citation] A citation contains body elements, consistently indented by at
least 3 spaces.
Normal ``<tt>`` (like the <tt> I just wrote here) needs to be shown with
the same style as anything else with ````this type of markup````.
It's common for programmers to give a code example inside of their
docstring::
from test_py_module import Foo
myclass = Foo()
myclass.dothismethod('with this argument')
myclass.flush()
print(myclass)
Here is a link to :py:meth:`capitalize`.
Here is a link to :py:meth:`__init__`.
"""
#: Doc comment for class attribute Foo.bar.
#: It can have multiple lines.
bar = 1
flox = 1.5 #: Doc comment for Foo.flox. One line only.
baz = 2
"""Docstring for class attribute Foo.baz."""
def __init__(self, qux, spam=False):
"""Start the Foo.
:param qux: The first argument to initialize class.
:type qux: string
:param spam: Spam me yes or no...
:type spam: bool
"""
#: Doc comment for instance attribute qux.
self.qux = 3
self.spam = 4
"""Docstring for instance attribute spam."""
def add(self, val1, val2):
"""Return the added values.
:param val1: First number to add.
:type val1: int
:param val2: Second number to add.
:type val2: int
:rtype: int
The parameters of this method are described in the parameter list.
"""
return val1 + val2
def capitalize(self, myvalue):
"""Return a string as uppercase.
:param myvalue: String to change
:type myvalue: string
:rtype: string
"""
return myvalue.upper()
def another_function(self, a, b, **kwargs):
"""
Here is another function.
:param a: The number of green hats you own.
:type a: int
:param b: The number of non-green hats you own.
:type b: int
:param kwargs: Additional keyword arguments. Each keyword parameter
should specify the name of your favorite cuisine.
The values should be floats, specifying the mean price
of your favorite dish in that cooking style.
:type kwargs: float
:returns: A 2-tuple. The first element is the mean price of all dishes
across cuisines. The second element is the total number of
hats you own: :math:`a + b`.
:rtype: tuple
:raises ValueError: When ``a`` is not an integer.
.. versionadded:: 1.0
This was added in 1.0
.. versionchanged:: 2.0
This was changed in 2.0
.. deprecated:: 3.0
This is deprecated since 3.0
"""
return sum(kwargs.values()) / len(kwargs), a + b
def add_numbers(a: int, b: int = 0) -> int:
"""Add two numbers together
:param a: The first number
:param b: The second number
Here is some more text.
"""
return a + b
def subtract_numbers(a: int, b: int = 0) -> int:
"""Subtract two numbers
:param a: The first number
:param b: The second number
"""
return a - b
|
