@@ -121,6 +121,139 @@ It's recommended to always use `"""strings like this"""` for docstrings,
121121even if the docstring is only one line long. This way it's easy to add
122122more stuff to it later.
123123
124+ ## Popular Docstring Formats
125+ 126+ There are different styles for writing docstrings. If you are contributing to
127+ another Python project, make sure to use the same style as rest of that project
128+ is using.
129+ 130+ If you are starting a new project, then you can use whichever style you
131+ want, but don't "reinventing the wheel"; use an existing style instead instead of
132+ making up your own. Here are some examples of popular docstring styles to choose
133+ from:
134+ 135+ ### Sphinx Style
136+ 137+ [ Sphinx] ( https://www.sphinx-doc.org/en/master/ ) is the Python documentation tool
138+ that [ the official Python documentation] ( https://docs.python.org/3/ ) uses.
139+ By default, sphinx expects you to write docstrings like this:
140+ 141+ ``` python
142+ class Vehicles :
143+ """
144+ The Vehicles object contains lots of vehicles.
145+ :param arg: The arg is used for ...
146+ :type arg: str
147+ :ivar arg: This is where we store arg
148+ :vartype arg: str
149+ """
150+ 151+ def __init__ (self arg ):
152+ self .arg = arg
153+ 154+ def cars (self distance , destination ):
155+ """ We can't travel a certain distance in vehicles without fuels, so here's the fuels
156+
157+ :param distance: The amount of distance traveled
158+ :type amount: int
159+ :param bool destinationReached: Should the fuels be refilled to cover required distance?
160+ :raises: :class:`RuntimeError`: Out of fuel
161+
162+ :returns: A Car mileage
163+ :rtype: Cars
164+ """
165+ ...
166+ ```
167+ 168+ ### Google Style
169+ 170+ Google Style is meant to be easier to read and use without a tool like sphinx.
171+ Sphinx can be configured to use that with
172+ [ sphinx.ext.napoleon] ( https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html ) .
173+ 174+ ``` python
175+ class Vehicles :
176+ """
177+ The Vehicles object contains lots of vehicles.
178+
179+ Args:
180+ arg (str): The arg is used for...
181+
182+ Attributes:
183+ arg (str): This is where we store arg.
184+ """
185+ 186+ def __init__ (self arg ):
187+ self .arg = arg
188+ 189+ def cars (self distance , destination ):
190+ """ We can't travel distance in vehicles without fuels, so here is the fuels
191+
192+ Args:
193+ distance (int): The amount of distance traveled
194+ destination (bool): Should the fuels refilled to cover the distance?
195+
196+ Raises:
197+ RuntimeError: Out of fuel
198+
199+ Returns:
200+ cars: A car mileage
201+ """
202+ ...
203+ 204+ ```
205+ 206+ ### Numpy Style
207+ 208+ [ Numpy] ( https://numpy.org/ ) is a large and popular Python library,
209+ and numpy developers have their own docstring style.
210+ 211+ ``` python
212+ class Vehicles :
213+ """
214+ The Vehicles object contains lots of vehicles.
215+
216+ Parameters
217+ ----------
218+ arg : str
219+ The arg is used for ...
220+ *args
221+ The variable arguments are used for ...
222+ **kwargs
223+ The keyword arguments are used for ...
224+
225+ Attributes
226+ ----------
227+ arg : str
228+ This is where we store arg.
229+ """
230+ 231+ def __init__ (self arg ):
232+ self .arg = arg
233+ 234+ def cars (self distance , destination ):
235+ """ We can't travel distance in vehicles without fuels, so here is the fuels
236+
237+ Parameters
238+ ----------
239+ distance : int
240+ The amount of distance traveled
241+ destination : bool
242+ Should the fuels refilled to cover the distance?
243+
244+ Raises
245+ ------
246+ RuntimeError
247+ Out of fuel
248+
249+ Returns
250+ -------
251+ cars
252+ A car mileage
253+ """
254+ pass
255+ ```
256+ 124257## Documenting other stuff
125258
126259Docstrings aren't actually limited to functions. You can use them for
0 commit comments