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

How can I use Sphinx' Autodoc-extension for private methods?

提问by cnu

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

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

.. autoclass:: ClassName
   :members:

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

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

回答by mariotomo

if you are using sphinx 1.1 or above, from the sphinx documentation site at http://www.sphinx-doc.org/en/master/ext/autodoc.html,

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

:special-members:
:private-members:

回答by cmcginty

One way to get around this is to explicitly force Sphinx to document private members. You can do this by appending automethodto the end of the class level docs:

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

回答by John

You can add this to conf.pyfile:

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

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

回答by rodfersou

Looking at apidoc code, we can change what sphinx-apidoc generate setting an environment variable:

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

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

You can also add this setup into your Makefile (if your package uses one):

您还可以将此设置添加到您的 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

回答by Vinay Sajip

Have you tried using a custom methodfor determining whether a member should be included in the documentation, using autodoc-skip-member?

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

回答by Vinay Sajip

No, private means private to the class and that it shouldn't be used from the public API. It's not meant to mean secret and for those of us wishing to use sphinx for full documentation of classes, excluding private methods is rather annoying.

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

The previous answer is correct. You will have to use a custom method as Sphinx does not currently support autodoc in conjunction with private methods.

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

回答by Mike Jarvis

If you only want to document specific private methods, not all of them, you can use the automethoddirective for each one, rather than :private-members:.

如果您只想记录特定的私有方法，而不是所有私有方法，您可以automethod为每个方法使用该指令，而不是:private-members:.

I often use leading underscore methods with the same name as a normal public method, which has the actual implementation of a function. The public method then has various sanity checks about the input arguments. The underscore method skips them, so they can be called for improved efficiency, but with less type safety.

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

E.g. (with apologies to @cmcginty for stealing their example)

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

Then to document _fly_to, but not _evaporate, you can do:

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

.. autoclass:: SmokeMonster
    :members:

    .. automethod:: SmokeMonster._fly_to

回答by S.Lott

Here's a hint: imagine that private means "secret".

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

That's why Sphinx won't document them.

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

If you don't mean "secret", consider changing their names. Avoid using the single-leading-underscore name in general; it doesn't help unless you have a reason to keep the implementation secret.

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