Sometimes a function in Python may accept an argument of a flexible type. Or it may return a value of a flexible type. Now I can't remember a good example of such a function right now, therefore I am demonstrating what such a function may look like with a toy example below.
I want to know how to write docstrings for such functions using the Sphinx documentation notation. In the example below, the arguments may be either str
or int
. Similarly it may return either str
or int
.
I have given an example docstrings (both in the default Sphinx notation as well as the Google notation understood by Sphinx's napoleon extension). I don't know if this is the right way to document the flexible types.
Sphinx default notation:
def add(a, b): """Add numbers or concatenate strings. :param int/str a: String or integer to be added :param int/str b: String or integer to be added :return: Result :rtype: int/str """ pass
Sphinx napoleon Google notation:
def add2(a, b): """Add numbers or concatenate strings. Args: a (int/str): String or integer to be added b (int/str): String or integer to be added Returns: int/str: Result """ pass
What is the right way to express multiple types for parameters or return values in docstrings that are meant to be processed by Sphinx?
Python 3.5 Union
type hints
https://docs.python.org/3/library/typing.html#typing.Union
For Python 2, I recommend using the exact same syntax as that Python 3 module, which will:
Example:
def f(int_or_float): """ :param int_or_float: Description of the parameter :type int_or_float: Union[int, float] :rtype: float """ return int_or_float + 1.0
Then when you have 3.5, you will write just:
from typing import Union def f(int_or_float : Union[int, float]) -> float: """ :param int_or_float: Description of the parameter """ return int_or_float + 1.0
I think it already has documentation generation support, but I haven't tested it yet: https://github.com/sphinx-doc/sphinx/issues/1968
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With