Question

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

.. autoclass:: ClassName
   :members:

问题是，它只记录了班级中的non-private methods。我如何也包括私人方法？

Answer 1

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

:special-members:
:private-members:

Answer 2

解决此问题的一种方法是明确强制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 3

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

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

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:。

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

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

这是一个暗示：想象私人意味着“秘密”。

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

如果您不是指“秘密”，请考虑更改其名称。一般避免使用单引号下划线名称;除非你有理由保密实施，否则它无济于事。

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

8 个答案: