如何使用 Sphinx 的 autodoc 来记录类的__ init__ (self)方法？

Sphinx 默认情况下不为 _ _ init _ _ (self)生成文档:

.. automodule:: mymodule
:members:

还有

..autoclass:: MyClass
:members:

在 config.py 中，设置以下内容只是将 _ _ init _ _ (self) docstring 附加到类 docstring 中(Sphinx autodoc 文档似乎同意这是预期的行为，但没有提到任何关于我试图解决的问题) :

autoclass_content = 'both'
55817 次浏览
小开
最佳答案

这里有三种选择:

  1. 为了确保 __init__()总是有文档记录，您可以在 conp.py 中使用 autodoc-skip-member，如下所示:

    def skip(app, what, name, obj, would_skip, options):
if name == "__init__":
return False
return would_skip


def setup(app):
app.connect("autodoc-skip-member", skip)

    这显式定义了不能跳过的 __init__(默认情况下是这样)。控件中的每个类都不需要任何额外的标记。第一个线人。

  2. special-members选项是 added in Sphinx 1.1。它使“特殊”成员(那些名称像 __special__)由 autodoc 文档化。

    自 Sphinx 1.2以来，该选项接受的参数使其比以前更加有用。

  3. 使用 automethod:

    .. autoclass:: MyClass
:members:


.. automethod:: __init__

    这必须为每个类添加(不能与 automodule一起使用，正如在对本答案第一版的注释中指出的那样)。

小开

你很接近了。你可以在你的 conf.py文件中使用 autoclass_content选项:

autoclass_content = 'both'
小开

在过去的几年里，我为各种不相关的 Python 项目编写了几个 autodoc-skip-member回调函数的变体，因为我希望像 __init__()、 __enter__()和 __exit__()这样的方法出现在我的 API 文档中(毕竟，这些“特殊方法”是 API 的一部分，而且还有什么地方比特殊方法的 docstring 更适合记录它们)。

最近，我选择了最好的实现，并将其作为我的 Python 项目(这是文件)的一部分。执行基本上可以归结为:

import types


def setup(app):
"""Enable Sphinx customizations."""
enable_special_methods(app)




def enable_special_methods(app):
"""
Enable documenting "special methods" using the autodoc_ extension.


:param app: The Sphinx application object.


This function connects the :func:`special_methods_callback()` function to
``autodoc-skip-member`` events.


.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
"""
app.connect('autodoc-skip-member', special_methods_callback)




def special_methods_callback(app, what, name, obj, skip, options):
"""
Enable documenting "special methods" using the autodoc_ extension.


Refer to :func:`enable_special_methods()` to enable the use of this
function (you probably don't want to call
:func:`special_methods_callback()` directly).


This function implements a callback for ``autodoc-skip-member`` events to
include documented "special methods" (method names with two leading and two
trailing underscores) in your documentation. The result is similar to the
use of the ``special-members`` flag with one big difference: Special
methods are included but other types of members are ignored. This means
that attributes like ``__weakref__`` will always be ignored (this was my
main annoyance with the ``special-members`` flag).


The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
return False
else:
return skip

是的，有更多的文档而不是逻辑: ——)。定义这样的 autodoc-skip-member回调比使用 special-members选项(对我来说)的好处是，special-members选项还支持像 __weakref__(可用于所有新风格类，AFAIK)这样的属性的文档，我认为它们是噪音而且一点用都没有。回调方法避免了这一点(因为它只在函数/方法上有效，并忽略了其他属性)。

小开

尽管这是一篇较早的文章，但对于那些目前正在查找它的人来说，版本1.8中还引入了另一个解决方案。根据 文件，您可以将 autodoc_default_options中的 special-members键添加到您的 conf.py。

例如:

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

这是一个变体，只包括 __init__，如果它有参数:

import inspect


def skip_init_without_args(app, what, name, obj, would_skip, options):
if name == '__init__':
func = getattr(obj, '__init__')
spec = inspect.getfullargspec(func)
return not spec.args and not spec.varargs and not spec.varkw and not spec.kwonlyargs
return would_skip


def setup(app):
app.connect("autodoc-skip-member", skip_init_without_args)
小开

只要这个提交被批准: https://github.com/sphinx-doc/sphinx/pull/9154，在下一个 Sphinx 版本(> 4.1.2)中就可以:

..autoclass:: MyClass1
:members:
:class-doc-from: "class"




..autoclass:: MyClass2
:members:
:class-doc-from: "init"

提交答案