Включите специальные специальные методы в сфинкс

У меня есть куча классов, которые используют "специальные методы":

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

теперь я хотел бы генерировать html-документацию для этого, используя Sphinx и autodoc. Как сообщить Sphinx о документе __contains__? Я попробовал добавить

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

до conf.py, но также включенный __dict__, который я определенно не хочу.

В настоящее время соответствующие части файла myproject.rst выглядят следующим образом:

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

изменить добавление

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

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

добавляет документацию по этому методу, но в отдельном разделе - не как часть документации класса Foo.

Ответ 1

Вы можете добавить:

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

В файл .rst, чтобы показать специальные элементы, кроме __dict__ и __weakref__

Ответ 2

Что сработало для меня, это добавить ".. automethod:: methodName"

в docstring класса, вместо того, чтобы делать это в файле .rst.

Итак, вы можете изменить "Foo docstring" на

"""
Foo docstring

.. automethod:: __contains__
"""

Ответ 3

Опция special-members теперь принимает аргументы (это новая функция в Sphinx 1.2).

Итак, это должно работать:

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

Ответ 4

В настоящее время я не в восторге от этого решения, поэтому я надеюсь, что кто-то сможет улучшить его. Однако, как я решил эту проблему, нужно сделать следующее:

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

Здесь мне действительно нужно сообщить autodoc, чтобы избежать документирования атрибутов класса (автоматически), а затем я должен добавить их обратно явно. Причина в том, что, очевидно, когда вы явно вставляете команды, первые явные. Если я просто говорю, чтобы добавить __contains__, то он появляется перед атрибутами, которые мне не нравятся.