Ответ 1
Вы можете добавить:
:special-members:
:exclude-members: __dict__,__weakref__
В файл .rst, чтобы показать специальные элементы, кроме __dict__ и __weakref__
Включите специальные специальные методы в сфинкс
У меня есть куча классов, которые используют "специальные методы":
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.
Ответы
Ответ 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__, то он появляется перед атрибутами, которые мне не нравятся.