По умолчанию Sphinx не создает документы для __init __ (self). Я пробовал следующее:
.. automodule:: mymodule
:members:
и
..autoclass:: MyClass
:members:
В conf.py установка следующего только добавляет строку документации __init __ (self) в строку документации класса ( документация Sphinx autodoc, похоже, согласна с тем, что это ожидаемое поведение, но ничего не упоминает о проблеме, которую я пытаюсь решить):
autoclass_content = 'both'
python
python-sphinx
autodoc
Джейкоб Марбл
источник
источник
"both" Both the class’ and the __init__ method’s docstring are concatenated and inserted.
-> Следовательно, это должна быть не только__init__(self)
строка документации класса, если она у вас есть. Можете ли вы предоставить тестовый пример, потому что если это так, это похоже на ошибку, верно?Ответы:
Вот три альтернативы:
Чтобы
__init__()
это всегда документировалось, вы можете использоватьautodoc-skip-member
файл conf.py. Как это:Это явно определяет,
__init__
что пропускать нельзя (что и есть по умолчанию). Эта конфигурация указывается один раз и не требует дополнительной разметки для каждого класса в исходном файле .rst.special-members
Вариант был добавлен в Сфинкса 1.1 . Он позволяет документировать "специальные" члены (с такими именами__special__
) в autodoc.Начиная с Sphinx 1.2, эта опция принимает аргументы, что делает ее более полезной, чем раньше.
Использование
automethod
:Это должно быть добавлено для каждого класса (не может использоваться
automodule
, как указано в комментарии к первой редакции этого ответа).источник
special-members
отлично работает с использованиемautomodule
. Используйте:special-members: __init__
только для документирования__init__
.Вы были близки. Вы можете использовать
autoclass_content
опцию в своемconf.py
файле:источник
autoclass_content = 'both'
опцию, которая документировала метод инициализации , но из-за этого автосводка появлялась дважды.За последние годы я написал несколько вариантов
autodoc-skip-member
обратных вызовов для различных несвязанных проектов Python, потому что мне нужны были такие методы, как__init__()
,__enter__()
и__exit__()
показать в моей документации API ( в конце концов, эти «специальные методы» являются частью API , и что лучше место документируйте их, чем в строке документации специального метода).Недавно я взял лучшую реализацию и сделал ее частью одного из моих проектов Python ( вот документация ). Реализация в основном сводится к следующему:
Да, документации больше, чем логики :-). Преимущество определения такого
autodoc-skip-member
обратного вызова по сравнению с использованиемspecial-members
параметра (для меня) заключается в том, что этотspecial-members
параметр также позволяет документировать такие свойства, как__weakref__
(доступны во всех классах нового стиля, AFAIK), которые я считаю шумными и совершенно бесполезными. Подход обратного вызова позволяет избежать этого (поскольку он работает только с функциями / методами и игнорирует другие атрибуты).источник
setup(app)
, чтобы его мог выполнить Sphinx.__init__
метод имеет непустую строку документации. Является ли?Несмотря на то, что это более старый пост, для тех, кто ищет его сейчас, есть еще одно решение, представленное в версии 1.8. Согласно документации , вы можете добавить
special-member
ключ в autodoc_default_options в свойconf.py
.Пример:
источник
Это вариант, который включает только в том
__init__
случае, если у него есть аргументы:источник