You should use None, as that is what your function actually returns: “””Prints the element given as input Args: x: any element Returns: None “”” All functions in Python return something. If you do not explicitly return a value, then they will return None by default: >>> def func(): … return … >>> print func() … Read more
It appears your teacher is a fan of How to Design Programs 😉 I’d tackle this as writing for two different audiences who won’t always overlap. First there are the docstrings; these are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be … Read more
There is no simple way to get a direct reference to a parameter of a function with sphinx and I don’t know an extension for this problem. The documentation of the python domain explains which objects can be cross referenced. A possible way to give the user a reference to parameter bar of function foo … Read more
I contacted PyCharm support, and this is what they said: For tuple please use (<type_1>, <type_2>, <type_3>, e t.c.) syntax. E.g.: “”” :rtype: (string, int, int) “”” This is confirmed in PyCharm’s documentation: Type Syntax Type syntax in Python docstrings is not defined by any standard. Thus, PyCharm suggests the following notation: … (Foo, Bar) … Read more
Python 3.10 | (pipe, binary or) Union type hint syntax sugar Once you get access, this will be the way to go, it is sweet: def f(i: int|str) -> int|str: if type(i) is str: return int(i) + 1 else: return str(i) The PEP: https://peps.python.org/pep-0604/ Documented at: https://docs.python.org/3.11/library/typing.html#typing.Union Union type; Union[X, Y] is equivalent to X … Read more
The napoleon-style docstrings as they are described in the sphinx docs (see the ExampleError class for their take on it) explicitly touch on your case: The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself. And if you do not want this behavior, you … Read more
This is a variation on Paul McGuire’s DocStringInheritor metaclass. It inherits a parent member’s docstring if the child member’s docstring is empty. It inherits a parent class docstring if the child class docstring is empty. It can inherit the docstring from any class in any of the base classes’s MROs, just like regular attribute inheritance. … Read more
I have created a Sphinx extension that parses both Google style and NumPy style docstrings, and converts them to standard reStructuredText. To use it, simply install it: $ pip install sphinxcontrib-napoleon And enable it in conf.py: # conf.py # Add autodoc and napoleon to the extensions list extensions = [‘sphinx.ext.autodoc’, ‘sphinxcontrib.napoleon’] More documentation on napoleon … Read more
Use functools.wraps() to update the attributes of the decorator: from functools import wraps def decorator(f): @wraps(f) def _decorator(): print ‘decorator active’ f() return _decorator @decorator def foo(): ”’the magic foo function”’ print ‘this is function foo’ help(foo) Also see the Standard Library documentation for functools.
An instancemethod gets its docstring from its __func__. Change the docstring of __func__ instead. (The __doc__ attribute of functions are writeable.) >>> class Foo(object): … def bar(self): … pass … >>> Foo.bar.__func__.__doc__ = “A super docstring” >>> help(Foo.bar) Help on method bar in module __main__: bar(self) unbound __main__.Foo method A super docstring >>> foo = … Read more