我如何使用 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_options = {
    "members": True,
    "undoc-members": True,
    "private-members": True
}

对于 sphinx <= 1.8

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

1.8 更新，感谢@partofthething。

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

您是否尝试过使用自定义方法来确定成员是否应该包含在文档中，使用 autodoc-skip-member？

Answer 5

查看 apidoc 代码，我们可以更改什么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

除了上面的答案之外，如果您使用命令 sphinx-apidoc

只需添加 -P 标志即可添加私有成员，
例如，

sphinx-apidoc -e -P -o docs/ local_Directory/

有关更多选项和标志信息，请查看官方文档：

https ://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

Answer 7

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

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

Answer 8

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

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

例如（对@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 9

这里有一个提示：想象一下 private 意味着“秘密”。

这就是为什么 Sphinx 不会记录它们。

如果您的意思不是“秘密”，请考虑更改他们的名字。 一般情况下避免使用单前导下划线名称； 除非你有理由对实施保密，否则它没有帮助。