How to document private attributes of a Python class in Sphinx

Question

I'd like to add descriptions of private attributes of a Python class to the Sphinx doc string of that class for code readability, but I'd like the auto generated doc to not show those attributes. Can I do this?

For example, if I have a class & doc string like this:

class Foo:
'''
My class description

:ivar attr1: Attribute 1 description
:ivar attr2: Attribute 2 description
'''

and I want to add a private attribute __attr3 to the list of attributes, how can I do that?

I see there is a ":meta private:" field as documented here, but that seems to be for private methods. Is there a way to use this field for attributes?

Answer 1

Yes, you can achieve this by using the :meta: directive in Sphinx. Although the :meta: directive is primarily intended for documenting private methods, you can adapt it to document private attributes as well.

Here's how you can use the :meta: directive to document private attributes in the Sphinx docstring:

class Foo:
    My class description

    :ivar attr1: Attribute 1 description
    :ivar attr2: Attribute 2 description
    :meta private attr3: Attribute 3 description (private)

    def __init__(self):
        self.attr1 = None
        self.attr2 = None
        self.__attr3 = None