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

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

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.


python python-sphinx autodoc
person mgilson    schedule 09.04.2013    source источник
comment
@GarethRees - Если вы хотите знать, мой вариант использования заключается в том, что класс Foo - это что-то вроде азбуки бедняка. Его строки документации сообщают пользователю, каково ожидаемое поведение его подклассов, и вызывает NotImplementedErrors. Я хочу задокументировать __contains__, чтобы пользователь знал, что должен означать if x in foo_subclass_instance, но с тем же успехом это мог быть специальный метод __getitem__, который ведет себя не совсем стандартным образом.   -  person mgilson    schedule 09.04.2013

Ответы (5)


arrow_upward
19
arrow_downward

Можете добавить:

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

В файл .rst для отображения специальных членов, кроме __dict__ и __weakref__

person arutaku    schedule 06.05.2013

arrow_upward
11
arrow_downward

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

в строке документации класса, а не в файле .rst.

Итак, вы можете изменить «строку документации Foo» на

"""
Foo docstring

.. automethod:: __contains__
"""
person rb3363392    schedule 28.02.2014

arrow_upward
8
arrow_downward

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

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

.. automodule:: myproject.foomodule
    :members:
    :undoc-members:
    :special-members: __contains__
    :show-inheritance:
person mzjn    schedule 28.02.2014

arrow_upward
3
arrow_downward

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

.. 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__, то он появится перед атрибутами, которые мне не нравятся.

person mgilson    schedule 09.04.2013

arrow_upward
3
arrow_downward

Начиная с Sphinx 1.8, вы можете использовать autodoc_default_options в conf.py. Пример:

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

Установка значения None или True эквивалентна присвоению директивам только имени опции.

Обратите внимание, что вы можете указать несколько значений в одной строке: '__init__,__call__'.

person Yaroslav Nikitenko    schedule 25.10.2019