How to express multiple types for a single parameter or a return value in docstrings that are 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:
- make porting easier, and possibly automatable, later on
- specifies a unique well defined canonical way to do things
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 Uniondef 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