如何在 sphinx 中自动记录私有实例属性？

Question

I usually initialize all instance attributes in __init__ :

def __init__(self):
"""
Initializer docstring.
"""
    self.test1 = None  #: test1 docstring
    self._test2 = None  #: test2 docstring
    self.test3 = None
    """test3 docstring"""
    self._test4 = None
    """test4 docstring"""

I would like to have all my instance attributes documented, including the private ones.

To generate the documentation I used the following code:

.. automodule:: module_name
    :members:
    :member-order: bysource
    :show-inheritance:
    :private-members:
    :special-members:

Yet private instance attributes are still omitted. What do I miss?

I use python 2.7, Sphinx 1.2.3, and sphinx-rtd-theme 0.1.9.

Thank you in advance.

Answer 1

I ran some additional tests and I still was not able to generate documentation for private attributes. I do not have time to run through autodoc code to verify whether the problem is on my side or it is just a designer's choice. I came up with the following work around though (in case somebody else runs in the similar problem):

1. I document all the public attributes in the class docstring (as suggested by NumPy style).

2. I document all the private attributes in the __init__ docstring (as I do initialize them all in there) using the notation for variables:

    :ivar _private_attribute: description. :vartype _private_attribute: int

As a result private attributes are documented in the Variables section. It is not perfect but it works for me.