Sphinx docs for composite data types

Question

Is there a standard or best practice in Sphinx for providing more exact specifications for composite Python data types? For example, I have a function that returns a dict mapping str to str and am using numpydoc style. Should I do something like:

Returns
-------
out : dict of str to str

or possibly dict of str: str?

For lists where the type of content is known, I've noticed that NumPy uses the format

foo : list of int

Is there a standard or best practice to follow for this common use case?

Answer 1

I'm not sure if it's a best practice but I usually do something like :returns: dict( str=str ). I think it's really what works best for you and your project. If you use something like PyCharm, it will recommend the "best" option for your doc strings, but it will slowly stop recommending things as it notices you do things differently. Stuff like PEP8 are more like guidelines (trying to do my best Pirates of the Caribbean impression here) and not so much hard set rules. The most important thing is whether or not you can read it.

One really good source of inspiration is Python's own documentation. If ever you're looking through it and you notice a nice looking page, look on the left side bar and click Show Source and then just copy that style...I do it all the time :)

Answer 2

Old question, but still was one of the top hits when searching for that info.

After more searching I found this in the Sphinx docs:

New in version 1.5.

Container types such as lists and dictionaries can be linked automatically using the 
following syntax:

:type priorities: list(int)  
:type priorities: list[int]
:type mapping: dict(str, int) 
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]