autodoc: class __init__ override not removed from docstring

Andrew Dawson avatarAndrew Dawson created an issue

If autodoc_docstring_signature = True and the user provides an override for a class __init__ method signature the signature is properly assigned, but the string specifying the override remains part of the docstring, unlike with other methods.

For example, the following code:

class MyClass(object):
    def __init__(self, *args, **kwargs):
        """
        __init__(arg1, arg2, kwarg1=False, kwarg2=None)

        Docstring with signature override.
        """
        pass

    def my_method(self, *args, **kwargs):
        """
        my_method(arg1, arg2, kwarg1=False, kwarg2=None)

        Another docstring with signature override.
        """
        pass

This will produce something like:

class MyClass(arg1, arg2, kwarg1=False, kwarg2=None)
    __init__(arg1, arg2, kwarg1=False, kwarg2=None)

    Docstring with signature override.

    my_method(arg1, arg2, kwarg1=False, kwarg2=None)
        Another docstring with signature override.

As you can see the __init__ override string remains part of the docstring, but the my_method override string is automatically removed as it should be.

This is with 1.2b1.

Comments (6)

  1. Takayuki Shimizukawa
    • changed status to open

    I reproduced this issue with:

    conf.py:

    autodoc_docstring_signature = True
    autoclass_content = 'init'  #or 'both'
    

    index.rst:

    .. autoclass:: mod.MyClass
    

    mod.py:

    class MyClass(object):
    
        def __init__(self, *args, **kwargs):
            """
            __init__(arg1, arg2, kwarg1=False, kwarg2=None)
    
            Docstring with signature override.
            """
            pass
    

    This will produce something like:

    class mod.MyClass(arg1, arg2, kwarg1=False, kwarg2=None)
        __init__(arg1, arg2, kwarg1=False, kwarg2=None)
    
        Docstring with signature override.
    

    The __init__ line should be eliminated.

  2. Takayuki Shimizukawa

    The __init__ line would be deleted when autodoc_docstring_signature = False ?

    A. Should keep __init__ line (Sphinx-1.x compatible):

    class mod.MyClass(*args, **kwargs)
        __init__(arg1, arg2, kwarg1=False, kwarg2=None)
    
        Docstring with signature override.
    

    B. Should remove __init__ line (introduce incompatibility):

    class mod.MyClass(*args, **kwargs)
        Docstring with signature override.
    

    The attached 1138-remove-docstring-signature-line.patch is A.

  3. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.