Where can I find more information about the new syntax supported in google-style docstrings with the napoleon sphinx-doc extension?

Question

The sphinx-doc style dcstrings example on the example here for version 1.3.4 shows that the optional arguments to the function / method should be documented as follows:

param2 (str, optional): The second parameter. Defaults to None.
  Second line of description should be indented.

But the same page for version 1.4a0 here shows the following way to do the same:

param2 (Optional[str]): The second parameter. Defaults to None.
    Second line of description should be indented.

But I see no explanation for this new syntax in the documentation . Where can I find more information about the new syntax supported in google-style docstrings with the napoleon extension of the sphinx-doc file?

Answer 1

tl; dr:

module_level_function, , , :

def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

    Parameter types -- if given -- should be specified according to
    `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.

    # ^^^^^ this! ^^^^

. -, , PEP 484 typing - , .

---

:

PEP 484 , PEP 3107; , . , :

def foo(a, b): 
    pass

:

def foo(a: int, b: str) -> None:
    pass

; typing.

typing (, , mumbo-jumbo), , , int, str et al. , Optional[str] , str, ' None , .

, , , . , , , :

 def func(param1)

:

param1 (List[int]): The first parameter containing a list of ints

List[int] .

---

:

, , mypy ( , PEP 484). , , :

Type                Description
----                -----------

int                 integer of arbitrary size
float               floating point number
bool                boolean value
str                 unicode string
bytes               8-bit string
object              an arbitrary object (object is the common base class)
List[str]           list of str objects
Dict[str, int]      dictionary from str keys to int values
Iterable[int]       iterable object containing ints
Sequence[bool]      sequence of booleans
Any                 dynamically typed value with an arbitrary type

, Any, Union , .

Answer 2

Optional[X] sphinx-doc, . typing : https://docs.python.org/3/library/typing.html