Incluir métodos especiales específicos en la esfinge.

Tengo un montón de clases que utilizan “métodos especiales”:

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 

ahora me gustaría generar la documentación html para esto usando Sphinx y autodoc. ¿Cómo le digo a Sphinx que documente __contains__ ? Intenté agregar

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

a conf.py , pero eso también incluía __dict__ que definitivamente no quiero.

Actualmente, las partes relevantes del archivo myproject.rst ven así:

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

edición añadiendo

 .. automodule:: myproject.foomodule :members: :undoc-members: :show-inheritance: .. automethod:: myproject.foomodule.Foo.__contains__ 

agrega documentación de ese método, pero en una sección separada, no como parte de la documentación de la clase Foo .

Puedes añadir:

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

Al archivo __dict__ para mostrar miembros especiales, excepto __dict__ y __weakref__

Lo que funcionó para mí es agregar el “.. automethod :: methodName

Directiva en la cadena de documentación de la clase, en lugar de hacerlo en el archivo .rst.

Por lo tanto, puede cambiar “Foo docstring” a

 """ Foo docstring .. automethod:: __contains__ """ 

La opción de miembros especiales ahora toma argumentos (esta es una nueva característica en Sphinx 1.2).

Así que esto debería funcionar:

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

Actualmente no estoy 100% emocionado con esta solución, así que espero que alguien pueda mejorarla. Sin embargo, la forma en que he resuelto este problema es hacer lo siguiente:

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

Aquí realmente necesito indicar autodoc para evitar documentar los atributos de la clase (automáticamente) y luego debo agregarlos de forma explícita. La razón es porque aparentemente, cuando se anidan explícitamente los comandos, los explícitos son lo primero . Si solo digo explícitamente que agregar __contains__ , entonces aparece antes de los atributos que no me __contains__ .