Allow special handling of __init__ methods #189
Description
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.