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

Question

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?

Answer 1

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 ,

:special-members:
:private-members:

Answer 2

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

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

Answer 3

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

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

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

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

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

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.

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.

Answer 7

If you only want to document specific private methods, not all of them, you can use the automethod directive for each one, rather than :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.

Eg (with apologies to @cmcginty for stealing their example)

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:

.. autoclass:: SmokeMonster
    :members:

    .. automethod:: SmokeMonster._fly_to

Answer 8

Other than above answers, if you are using the command sphinx-apidoc

just add the -P flag to add the private members, for example

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

for more options and flags info check the official documentation:

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

Answer 9

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

That's why Sphinx won't document them.

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.