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 attribute

   def __init__(self):
       self.x = 12

   def say_hello(self):
       """
       say_hello(self) -> None

       Issue a friendly greeting.
       """
       print "Hello! x is {0}".format(self.x)

   def __contains__(self,other):
       """Implement ``other in self``"""
       return other == self.x

now I would like to generate html documentation for this using Sphinx and autodoc. How do I tell Sphinx to document __contains__? I tried adding

autodoc_default_flags = ['members', 'undoc-members', 'special-members']

to conf.py, but that also included __dict__ which I definitely don't want.

Currently, the relevant portions of the myproject.rst file look like:

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

edit adding

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

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

does add documentation of that method, but in a separate section -- Not as part of the Foo class documentation.

回答1:

You can add:

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

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

回答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__
"""

回答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:

回答4:

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.

回答5:

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__'.