CODEWITHSUNDEEP
pythonpython-sphinxautodoc
cnu
cnu

Reputation: 37205

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

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?

Upvotes: 32

Views: 21278

Answers (9)

John
John

Reputation: 180

You can add this to conf.py file:

autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "private-members": True
}

For sphinx <= 1.8

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

1.8 update thanks to @partofthething.

Upvotes: 18

Elie Eid
Elie Eid

Reputation: 981

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

Upvotes: 3

Mike Jarvis
Mike Jarvis

Reputation: 919

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.

E.g. (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

Upvotes: 2

mariotomo
mariotomo

Reputation: 9728

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:

Upvotes: 36

rodfersou
rodfersou

Reputation: 944

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

Upvotes: 4

cmcginty
cmcginty

Reputation: 116948

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

Upvotes: 10

df
df

Reputation:

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.

Upvotes: 2

S.Lott
S.Lott

Reputation: 391820

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.

Upvotes: -11

Vinay Sajip
Vinay Sajip

Reputation: 99297

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

Upvotes: 4

Related Questions