python - Sphinx 没有记录复杂的 Enum 类

Question

在我的代码中，我有一些属于复杂枚举类型的类。例如:

class ComplexEnum(SomeOtherClass, Enum):
    """ Some documentation """

    MEMBER1 = SomeOtherClass(1)
    MEMBER2 = SomeOtherClass(2)

    def __init__(self, arg):
        """ more doc """
        pass

    def somemethod(self):
        """ more doc """
        pass

    @classmethod
    def someclassmethod(cls, otherparam):
        """ more doc """
        pass

当我现在使用 autodoc 使用 Sphinx 创建文档时，会跳过此类。我尝试将这样的自定义文档添加到我的 conf.py 文件中:

from sphinx.ext.autodoc import ClassDocumenter

class MyClassDocumenter(ClassDocumenter):
    objtype = 'ComplexEnum'
    directivetype = 'class'

    @classmethod
    def can_document_member(cls, member, membername, isattr, parent):
        return isinstance(member, ComplexEnum)

def setup(app):
    app.add_autodocumenter(MyClassDocumenter)

但这也不起作用。

如何使 sphinx 记录此类类？

Answer 1

这是 Sphinx autodoc 中使用 Enum 时出现的错误。

可以通过仔细编写 .rst 文件来解决这个问题。

话虽如此，我认为这是为了:

对应的.rst:

my_module module
================

.. automodule:: my_module
   :exclude-members: ComplexEnum


   .. autoclass:: ComplexEnum
      :members: some_method
      :show-inheritance:
      :exclude-members: MEMBER1, MEMBER2, __init__, some_classmethod

      .. automethod:: some_classmethod  

      .. autoattribute:: MEMBER1
         :annotation: = SomeOtherClass(1)

      .. autoattribute:: MEMBER2
         :annotation: = SomeOtherClass(2)

      .. automethod:: __init__

   .. autoclass:: SomeOtherClass
      :special-members: __init__

我稍微修改了代码以更好地解释解决方法的一些细节:

from enum import Enum


class SomeOtherClass:
    """ SomeOtherClass documentation """

    def __init__(self, other_arg):
        """Example of docstring on the __init__ method.

        Args:
            other_arg (int): Description of `other_arg`.
        """
        self.other_arg = other_arg


class ComplexEnum(SomeOtherClass, Enum):
    """ComplexEnum documentation."""

    #: :py:mod:`~my_package.my_module.SomeOtherClass`: MEMBER1 docstring comment.
    MEMBER1 = SomeOtherClass(1)
    #: :py:mod:`~my_package.my_module.SomeOtherClass`: MEMBER2 docstring comment.
    MEMBER2 = SomeOtherClass(2)

    def __init__(self, complex_arg):
        """Example of docstring on the __init__ method.

        Args:
            complex_arg (int): Description of `complex_arg`.
        """
        self.complex_arg = complex_arg
        super().__init__(complex_arg)

    def some_method(self):
        """The doc of some_method."""
        pass

    @classmethod
    def some_classmethod(cls, some_arg):
        """The doc of some_classmethod.

        Args:
            some_arg (int): Description of `some_arg`.
        """
        pass

你的conf.py可以保留标准，我只添加extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']来启用谷歌风格的评论。

<小时/><小时/>

到目前为止，在 @mzjn 贡献的链接和您的帖子中已经确定了触发该错误的具体条件组合，即:

1. 使用@classmethod + IntEnum。
2. 使用@classmethod + 多重继承，父级之一是Enum。

应该注意的是:使用带有@classmethod的简单枚举不会触发该错误。 (在这种情况下，.. autoclass:: 的行为符合预期，并且几乎处理所有事情。)

<小时/><小时/>

该错误会影响多个 autodoc 指令及其选项，导致它们出现意外行为。

编写 .rst 时必要的解决方法如下:

1. 请勿在枚举中使用 :undoc-members:，否则 caos 会崩溃。如果这样做，则始终包含 @classmethod 而不会获取描述符或文档字符串，并且使用 :exclude-members: 将其排除将无效。

2. 接下来的__init__是最有问题的方面。有效的方法是使用 :exclude-members: 排除它，并显式使用 .. automethod::__init__ 。

3. 与上述一起:您不能在 .rst 中使用 :automethod: 将 @classmethod 放在 __init__ 旁边，否则整个 @classmethod 会被“吸收”为 __init__ 文档字符串的一部分。

4. 对我来说，最有效的方法是使用 :members: 和 :exclude-members: 显式包含/排除枚举的所有部分。这保证了 autodoc 指令/选项的行为的最佳一致性。

<小时/><小时/>

两个最后的注释与使用 Sphinx 记录 Enum 相关(与错误没有直接关系)。

1. 在记录 Enum 成员时，为了获得最佳一致性，请使用 #: 语法而不是三引号 ''' 或内联 # 。原因是，因为后者经常被Sphinx“混淆”甚至丢失。

   • 即使使用 ..member-order: by source 作为指令选项或在配置中，上述情况通常也是如此。

2. 最后，如果您希望枚举成员的值显示在文档中，就像它们出现在类声明语法中一样。根据我的经验，最好的方法是使用 :annotation:，如 .rst 中所示。否则，枚举成员将显示在如下文档中:

将 Python 3.8 与 Sphinx v2.2.2 结合使用。