Skip to content

Commit 5e514cb

Browse files
voetbergrdimaio
authored andcommitted
Add docstring section
1 parent 7e588fc commit 5e514cb

File tree

1 file changed

+42
-0
lines changed

1 file changed

+42
-0
lines changed

docs/developer/style_guide.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,3 +248,45 @@ tools/run_pyright.sh generate {report_output_path.json}
248248
```
249249
The first action will raise an error if your commits introduce more un-annotated types than it solves,
250250
and the second ensures the added types are consistent with the rest of the codebase.
251+
252+
253+
# Docstring Style
254+
Python Client documentation is autogenerated from docstrings, and need to follow a defined style.
255+
Client Docstrings use the `numpy` style, a [description of the style can be found here](https://numpydoc.readthedocs.io/en/latest/format.html)
256+
and [an example can be found here](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html).
257+
258+
Notably, docstrings should **not** explicitly include types, as they are automatically added from the type annotation.
259+
260+
A basic example can be seen below:
261+
262+
```python
263+
264+
def function(param1: int, param2: Optional[str] = None) -> None:
265+
"""
266+
The function description
267+
268+
Parameters
269+
----------
270+
param1
271+
The first parameter
272+
param2
273+
The second parameter
274+
275+
Returns
276+
-------
277+
None
278+
Nothing is returned
279+
280+
Raises
281+
-------
282+
TypeError
283+
If something goes wrong
284+
285+
286+
Examples
287+
--------
288+
>>> function(1)
289+
>>> function(1, "one")
290+
"""
291+
292+
```

0 commit comments

Comments
 (0)