Python Sphinx autodoc and decorated members

Added in version 1.1 you can now override the method signature by providing a custom value in the first line of your docstring.

http://sphinx-doc.org/ext/autodoc.html#confval-autodoc_docstring_signature

@checkStale
def open(self):
    """
    open()
    Some docs.
    """
    # Code

To expand on my comment:

Have you tried using the decorator package and putting @decorator on checkStale? I had a similar issue using epydoc with a decorated function.

As you asked in your comment, the decorator package is not part of the standard library.

You can fall back using code something like the following (untested):

try:
    from decorator import decorator
except ImportError:
    # No decorator package available. Create a no-op "decorator".
    def decorator(f):
        return f

Add '.__ doc __':

def checkStale(f):
    @wraps(f)
    def newf(self, *args, **kwargs):
       if self._stale:
          raise Exception
       return f(self, *args, **kwargs)
    newf.__doc__ = f.__doc__
    return newf

And on decorated function add:

@checkStale
def open(self):
    """
    open()
    Some docs.
    """
    # Code

I had the same problem with the celery @task decorator.

You can also fix this in your case by adding the correct function signature to your rst file, like this:

.. autoclass:: Bus
    :members:

    .. automethod:: open(self)
    .. automethod:: some_other_method(self, param1, param2)

It will still document the non-decorator members automatically.

This is mentioned in the sphinx documentation at http://www.sphinx-doc.org/en/master/ext/autodoc.html#directive-automodule -- search for "This is useful if the signature from the method is hidden by a decorator."

In my case, I had to use autofunction to specify the signature of my celery tasks in the tasks.py module of a django app:

.. automodule:: django_app.tasks
    :members:
    :undoc-members:
    :show-inheritance:

    .. autofunction:: funct1(user_id)
    .. autofunction:: func2(iterations)