20

我有一堆使用“特殊方法”的类：

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

现在我想为此使用 Sphinx 和 autodoc 生成 html 文档。我如何告诉 Sphinx 记录__contains__？我尝试添加

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

to 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类文档的一部分。

4

5 回答 5

20

你可以加：

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

到.rst文件中以显示特殊成员，除了__dict__和__weakref__

于 2013-05-06T13:12:57.003 回答
12

对我有用的是添加“.. automethod:: methodName ”

类的文档字符串中的指令，而不是在 .rst 文件中执行。

因此，您可以将“Foo docstring”更改为

"""
Foo docstring

.. automethod:: __contains__
"""
于 2014-02-28T05:55:23.983 回答
9

special-members选项现在接受参数（这是 Sphinx 1.2 中的新功能）。

所以这应该工作：

.. automodule:: myproject.foomodule
    :members:
    :undoc-members:
    :special-members: __contains__
    :show-inheritance:
于 2014-02-28T08:10:59.157 回答
4

从Sphinx 1.8 开始，您可以在conf.py. 例子：

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

将 None 或 True 设置为该值相当于只为指令提供选项名称。

请注意，您可以在一个字符串中给出多个值：' __init__,__call__'。

于 2019-10-25T09:52:34.090 回答
3

我目前对这个解决方案不是 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__，那么它会显示在我不喜欢的属性之前。

于 2013-04-09T14:48:50.603 回答