# FUNCTION DEFINITION:
def enlarge(n:float) -> float: # OBSERVE THE TYPE HINTS
return n * 100.0
# FUNCTION INVOCATIONS:
print(enlarge(9))
print(enlarge(3))
= 10
x print(enlarge(x))
900.0
300.0
1000.0
Documentation helps people (or your future self) understand how to use your software.
Benefits of documentation include higher likelihood of the software being adopted and supported by others.
Specific ways of implementing documentation in Python are with docstrings and type hints.
When Python code is documented according to certain conventions, it is possible to auto-generate entire documentation reference websites, using auto-documentation tools.
Docstrings allow Python developers to document their code in a way which can be interpreted by other computers and humans alike.
“The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.” - PEP 257
Example function, before documentation:
def enlarge(n):
return n * 100
Example function, complete with docstring:
def enlarge(n):
"""
Enlarges a number.
Params:
n : (numeric, like int or float) the number to be enlarged
Examples:
enlarge(8)
enlarge(4.5)
"""
return n * 100
The multiline string can look intimidating, but docstrings have practical benefits. Python tools and text editors will recognize the docstring and show a helper message to anyone who is trying to use / invoke that function:
You don’t need to follow any specific conventions with your docstrings for them to be valid. However if you are looking for some specific recommendations for how to structure your docstrings, consider adopting one of the following conventions:
Tools like Sphinx, MkDocs, Jupyter Book, and Quarto can generate auto-generate entire documentation sites based on docstring content, especially if the docstrings conform to certain conventions. Read The Docs is a popular hosting provider for Python package documentation sites.
To create your own auto-documentation site for a Python package, feel free to leverage this Quarto Python Package Autodoc Template repository.
Example Auto-Documentation Site: Pandas Package
Observe the documentation site for the DataFrame
class, and corresponding source code. Notice the phrase “Two-dimensional, size-mutable, potentially heterogeneous tabular data”, as well as the function parameters, are coming from the docstring.
Example Auto-Documentation Site: Truthbrush
Observe the documentation site for the Api
class, and corresponding source code. Observe these examples of Google-style docstring formatting.
class Api:
"""A client for interfacing with the API.
Params:
username (str): The user name for logging in to the API.
password (str): The password for logging in to the API.
Examples:
Initialize the client by passing your username and password:
```python
from my_package import Api
client = Api(username="yourname", password="yourpass")
```
"""
Another way of documenting functions more formally is a type hint.
Type hints allow us to specify:
:
) to the right of each parameter name->
) to the right of the function definition# FUNCTION DEFINITION:
def enlarge(n:float) -> float: # OBSERVE THE TYPE HINTS
return n * 100.0
# FUNCTION INVOCATIONS:
print(enlarge(9))
print(enlarge(3))
= 10
x print(enlarge(x))
900.0
300.0
1000.0
In this example we are using a basic datatype (float
) in the type hints, but for more advanced type hints, we can consider using the typing
module. For more information, consult the type hints cheat sheet.
Ultimately these type hints are just suggestions, and they won’t perform validations or prevent different datatypes from being passed in.