From the Sphinx documentation:
returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.
You might also benefit from:
raises, raise, except, exception: That (and when) a specific exception is raised.
So, as one example:
def get_previous_release(release_id):
"""
Holt Vorgängeritem eines Items mit der ID release_id
:param release_id: ID des items für das Release
:type release_id: int
:returns: appropriate release object
:rtype: AlphaRelease, BetaRelease, or VRelease
:raises ValueError: if release_id not an int
:raises LookupError: if given release_id not found
:raises TypeError: if id doesn't reference release
"""
... # your code here
Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:
:rtype: Union[AlphaRelease, BetaRelease, VRelease]
Answer from Jonathan Eunice on Stack OverflowFrom the Sphinx documentation:
returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.
You might also benefit from:
raises, raise, except, exception: That (and when) a specific exception is raised.
So, as one example:
def get_previous_release(release_id):
"""
Holt Vorgängeritem eines Items mit der ID release_id
:param release_id: ID des items für das Release
:type release_id: int
:returns: appropriate release object
:rtype: AlphaRelease, BetaRelease, or VRelease
:raises ValueError: if release_id not an int
:raises LookupError: if given release_id not found
:raises TypeError: if id doesn't reference release
"""
... # your code here
Unfortunately there is not a strict or canonical choice in the Sphinx grammar and vocabulary for multiple return types. Often one would state a super-type of all the types that might be returned, if one existed (GenericRelease e.g.). But Python is just now, in its mid- to late-Python 3 era, defining a richer type notation. The typing module defines an evolving new grammar for such types independent of the old Sphinx definitions. If you wished to use this emerging standard, you might try something like:
:rtype: Union[AlphaRelease, BetaRelease, VRelease]
Python 3.10 | (pipe, binary or) Union type hint syntax sugar
This is going to be the way forward in the future, so clean:
def f(i: int | str) -> int | str:
if type(i) is str:
return int(i) + 1
else:
return str(i)
Also is also already fully supported by Sphinx:

More details at: How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?
Properly documenting the return type in the "Returns" section when using google docstring style
coding standards - Python method docstring: to use or not to use Args: Returns: - Software Engineering Stack Exchange
python docstring for conditional return - Stack Overflow
python - Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters? - Software Engineering Stack Exchange
Writing good documentation is an art unto itself. Repeating yourself (e.g., repeating the variable name without underscores) is valueless; e.g., ++i; // increment i. If you're just repeating variable names without underscores, then you're not adding to anyone's understanding of the code.
I think it's always important to document what exceptions your methods throw. Return values aren't always as obvious as the original programmer thinks they are, so that's usually useful to document as well. (Again, if your method is get_foo(), saying "returns a foo" doesn't add anything.)
One thing to point out about that mypy example, the authors are using type hints which replaces a lot of what would be included in a docstring:
def warn(self, msg: str, context: Context, file: Optional[str] = None,
origin: Optional[Context] = None)
Just from this, I know exactly what this method expects. Without it:
def warn(self, msg, context, file = None, origin = None)
I know a lot less.
I can not give you a definite answer, since such documentation also is sort of work and as such should be done, if useful. Generally speaking, only useful functionality should be exposed to the user and the application should be easy to use and understand.
Arguments Even obvious things can be exported for fast lookup. This is usually helpful for long and tedious methods. Optional parameters can be easily integrated by default parameters.
Return values With python it can be a pain to look up return values by inspecting objects (without source code), so when the source code is not at hand this should be done.
Side effects This is a quite vague term, but at least thread-safety support should be annotated in mixed applications cases (or explicitely). Default however is not thread-safe.
Exceptions Enforcing programmer/user input should be definitely documented, since this will cause crashing behavior.
In a small project, and as such internal project, for given knowledge and (hopefully) code, it does not make too much sense to comment everything. Concentrate on data structures and use cases for functions.