Does Sphinx have a supported standard for documenting the arguments or return value types that are not a simple, single object?
For instance, in the following, arg1 is a str, arg2 is a list of str, and arg3 is either a str or int. How can you specify collection or composite types in Sphinx? Or is there no common standard for this?
def function(arg1, arg2, arg3): """ :param arg1: Argument 1 :type arg1: str :param arg2: Argument 2 :type arg2: list[str] :param arg3: Argument 3 :type arg3: str or int """ pass
Python 3.5 type hints, while not yet supported by Sphinx, will likely make Sphinx type annotations obsolete one day. https://docs.python.org/3/library/typing.html
For now, I recommend using the exact same syntax as that module, which will:
- make porting easier, and possibly automatable, later on
- specifies a unique well defined way to do things
Example:
def f(list_of_int): """ :type list_of_int: List[int] :rtype: int """ return list_of_int[0] + list_of_int[1]
Then when you have 3.5, you will write just:
def f(list_of_int : List[int]) -> int: return list_of_int[0] + list_of_int[1]
The str or int part can be expressed with Union: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?
翻译