Include Specific Special-methods In Sphinx

I have a bunch of classes which use 'special-methods': class Foo(object): 'Foo docstring' attr1 = 'Attribute!' #: first attribute attr2 = 'Another Attribute!' #: second a

Solution 1:

You can add:

:special-members:
:exclude-members: __dict__,__weakref__

To the .rst file in order to show special members, except __dict__ and __weakref__

Solution 2:

What worked for me is adding the ".. automethod:: methodName"

directive in the docstring of the class, instead of doing it in the .rst file.

So, you can change "Foo docstring" to

"""
Foo docstring

.. automethod:: __contains__
"""

Solution 3:

The special-members option now takes arguments (this is a new feature in Sphinx 1.2).

So this should work:

.. automodule:: myproject.foomodule
    :members:
    :undoc-members:
    :special-members: __contains__
    :show-inheritance:

Solution 4:

Since Sphinx 1.8, you can use autodoc_default_options in conf.py. Example:

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Setting None or True to the value is equivalent to giving only the option name to the directives.

Note that you can give several values in one string: '__init__,__call__'.

Solution 5:

I'm currently not 100% thrilled with this solution, so I hope someone can come along an improve it. However, the way I've solved this problem is to do the following:

.. automodule:: myproject.foomodule
    :members:
    :undoc-members:
    :show-inheritance:

    .. autoclass:: myproject.foomodule.Foo
        :exclude-members: attr1,attr2

        .. autoattribute:: myproject.foomodule.Foo.attr1 

        .. autoattribute:: myproject.foomodule.Foo.attr2 

        .. automethod:: myproject.foomodule.Foo.__contains__

Here I actually need to tell autodoc to avoid documenting the class attributes (automatically) and then I need to add them back on explicitly. The reason is because apparently when you explicitly nest commands, the explicit ones come first. If I only explicitly say to add __contains__, then it shows up before the attributes which I didn't like.