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

Question

The sphinx-doc napoleon Google style docstrings example here for version 1.3.4 shows that optional arguments for a 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 thing:

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

But I don't see any explanation of this new syntax in the documentation. Where can I find more information about new syntax supported in Google style docstrings with the napoleon extension of sphinx-doc?

Answer 1

In a tl;dr fashion:

Looking at the documentation in the beginning of function module_level_function that you linked, one can see that:

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! ^^^^

The final line contains a hint. Apparently, the notation introduced in PEP 484 assisted by the typing module is what you're seeing.

---

A small intro on the notation:

PEP 484 is based on function annotations as described in PEP 3107; essentially each function parameter can have an optional type specifier after its name. So, for a function like:

def foo(a, b): 
    pass

You could annotate their types in the following way:

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

The introduction of type hinting brought with it a need to formalize the way types will be indicated; this is where the typing module comes in.

The typing module contains a good set of abstract types (and, generally, type theory mumbo-jumbo) for you to specify additional types other than standard built-ins like int, str et al. For example, the Optional[str] notation indicates that the parameter can take either a str type or a 'type' of None i.e it's optionally a string.

So in a nutshell, they're using the notation defined with the introduction of type hints for documenting the type of the parameters. This means that if you have a function that takes an argument that is a List of integers:

 def func(param1)

The documentation for it should look something like this:

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

Where List[int] comes from the notation in the typing module.

---

Some more examples:

Some examples where this specific notation is defined and furthe explained can be found in the documentation of mypy (a static checker that inspired PEP 484). Common cases that one might need to document in their code are contained in the table of built-in types:

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

Others, like Any, Union are defined here while generic notation described here.