28

I am using Sphinx for documenting my python project. I have the autodoc extension enabled and have the following in my docs.

.. autoclass:: ClassName
   :members:

The problem is, it only documents the non-private methods in the class. How do I include the private methods too?

4

8 回答 8

32

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

:special-members:
:private-members:
于 2011-10-12T12:47:28.183 回答
13

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

autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']
于 2017-06-19T19:49:51.010 回答
9

解决此问题的一种方法是显式强制 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
于 2011-05-24T07:02:59.790 回答
4

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

于 2009-07-19T06:28:49.027 回答
4

查看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
于 2015-05-09T19:14:55.917 回答
2

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

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

于 2009-07-29T13:00:36.573 回答
1

如果您只想记录特定的私有方法，而不是全部，您可以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
于 2019-08-06T12:43:28.300 回答
-8

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

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

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

于 2009-07-19T11:37:02.663 回答