PyCQA
Allow special handling of __init__ methods
When rendering documentation using Sphinx autodoc, the __init__ method is handled in a special way. The way it is handled depends on the value of autoclass_content.
Consider the following simple class:
class Foo:
"""
A class for handling all sorts of foos and bars.
Because foos and bars are complicated enough.
"""
def __init__(self, bar):
"""
Args:
bar: the bar to handle using foo.
"""
If autoclass_content is set to both, this seems very legitimate. However, pep257 complains about this:
$ pep257 spam.py
spam.py:17 in public method `__init__`:
D400: First line should end with a period (not ':')
spam.py:17 in public method `__init__`:
D205: 1 blank line required between summary line and description (found 0)
Instead, autoclass_content can be set to class and everything can be moved into the class docstring.
class Foo:
"""
A class for handling all sorts of foos and bars.
Because foos and bars are complicated enough.
Args:
bar: the bar to handle using foo.
"""
def __init__(self, bar):
...
But this will trigger the following warning:
spam.py:20 in public method `__init__`:
D102: Missing docstring in public method
And the last variant:
class Foo:
def __init__(self, bar):
"""
A class for handling all sorts of foos and bars.
Because foos and bars are complicated enough.
Args:
bar: the bar to handle using foo.
"""
triggers this:
$ pep257 spam.py
spam.py:9 in public class `Foo`:
D101: Missing docstring in public class
As a workaround I've applied this:
class Foo:
"""
A class for handling all sorts of foos and bars.
Because foos and bars are complicated enough.
"""
def __init__(self, bar):
"""
Initialize the foo.
Args:
bar: the bar to handle using foo.
"""
But I think that's simply very ugly.
I think __init__ should not be treated as a magic or public method, but as a separate use case.
Additionally I think it makes sense to add a rule to forbid a docstring on __init__ methods. This makes sense when using the class value for autoclass_content, which is the default.
Would a first-pass solution be to allow a switch for documentation type? The default (current) could be __init__, the one for the last version would be class, and the first one you mention could just be boht for the concatenation of the two. This hopefully wouldn't be too hard to implement.
I have the same issue. A solution would be very nice. @remcohaszing thanks for reporting.
Maybe someone should post that the issue is solved for the autoclass_content = 'class' case (autoapi_python_class_content in the case of AutoAPI), by introducing D107.
See http://www.pydocstyle.org/en/stable/error_codes.html
