如何将 Sphinx 的 Autodoc 扩展用于私有方法？

Question

我正在使用 Sphinx 来记录我的 python 项目。我启用了 autodoc 扩展，并且在我的文档中有以下内容。

.. autoclass:: ClassName
   :members:

问题是，它只记录了类中的非私有方法。我如何也包含私有方法？

Answer 1

如果您使用的是 sphinx 1.1 或更高版本，请访问 sphinx 文档站点 http://www.sphinx-doc.org/en/master/ext/autodoc.html，

:special-members:
:private-members:

Answer 2

您可以将此添加到conf.py 文件中：

autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']

Answer 3

解决此问题的一种方法是明确强制 Sphinx 记录私有成员。您可以通过将automethod 附加到类级别文档的末尾来做到这一点：

class SmokeMonster(object):
   """
   A large smoke monster that protects the island.
   """
   def __init__(self,speed):
      """
      :param speed: Velocity in MPH of the smoke monster
      :type  speed: int

      .. document private functions
      .. automethod:: _evaporate
      """
      self.speed = speed

   def _evaporate(self):
      """
      Removes the smoke monster from reality. Not to be called by client.
      """
      pass

Answer 4

您是否尝试过使用custom method 来确定是否应将成员包含在文档中，使用autodoc-skip-member？

Answer 5

查看apidoc code，我们可以通过设置环境变量来更改 sphinx-apidoc 生成的内容：

export SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'

您也可以将此设置添加到您的 Makefile 中（如果您的包使用了一个）：

docs:
    rm -rf docs/api
    SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance' sphinx-apidoc -o docs/api/ intellprice
    $(MAKE) -C docs clean
    $(MAKE) -C docs html

Answer 6

不，私有意味着类私有，并且不应从公共 API 中使用它。这并不意味着秘密，对于我们这些希望使用 sphinx 来完整记录类的人来说，不包括私有方法是相当烦人的。

前面的答案是正确的。您必须使用自定义方法，因为 Sphinx 目前不支持将 autodoc 与私有方法结合使用。

Answer 7

如果您只想记录特定的私有方法，而不是全部，您可以对每个方法使用automethod 指令，而不是:private-members:。

我经常使用与普通公共方法同名的前导下划线方法，它具有函数的实际实现。然后，公共方法对输入参数进行各种健全性检查。 underscore 方法会跳过它们，因此可以调用它们以提高效率，但类型安全性较低。

例如（向@cmcginty 盗用他们的例子表示歉意）

class SmokeMonster(object):
   """
   A large smoke monster that protects the island.
   """
   def __init__(self, speed, initial_position):
      """
      :param speed: Velocity in MPH of the smoke monster
      :param inital_position: Position of the smoke monster
      """
      self.speed = speed
      self.position = initial_position

   def _evaporate(self):
      """
      Removes the smoke monster from reality. Not to be called by client.
      """
      pass

   def fly_to(self, position):
      """
      Have the monster fly to the specified position.

      :param position: Desired location for the monster to fly to.
      """
      if not position.is_valid():
          raise ValueError("Invalid position: " + str(position))
      if not self.can_fly():
          raise RuntimeError("Smoke monster is not currently able to fly.")

      self._fly_to(position)

   def _fly_to(self, position):
      """Equivalent to :meth:`SmokeMonster.fly_to`, but without the safety checks.

      Not normally recommended for end users, but available if you need to
      improve efficiency of the `fly_to` call and you already know it is safe
      to call.
      """
      self.position = position

然后记录_fly_to，而不是_evaporate，你可以这样做：

.. autoclass:: SmokeMonster
    :members:

    .. automethod:: SmokeMonster._fly_to

Answer 8

这里有个提示：想象一下 private 的意思是“秘密”。

这就是 Sphinx 不会记录它们的原因。

如果您不是指“秘密”，请考虑更改他们的名字。一般避免使用单前导下划线名称；除非您有理由对实现保密，否则它无济于事。