How to document a single private attribute with Sphinx autodoc?

Question

I'm using sphinx and the autodoc extension to automatically generate documentation from docstrings in my python modules.

I currently using the automodule directive to document all the public members of the module

.. automodule::
    :members:

My module also has a number of private attributes. I'd like to include one of them in the documentation.

Is there a way to tell automodule to document all public members and also this one private member? I've tried using the :private-members: option, but that includes all private members. I've also tried manually specifying the private attribute, but then it doesn't document any of the public members.

.. automodule::
    :members: _PRIVATE_ATTR

I'd like to avoid having to manually list every single public member just to add this one private member.

Is there a way to do this with autodoc?

Answer 1

Here is what I would expect to work (tested with Sphinx 1.8.3):

.. automodule:: yourmodule
   :members:
   :private-members: _PRIVATE_ATTR

But it does not quite work. If the :private-members: option is given, with or without arguments, all private members are included (provided that they have a docstring).

The :special-members: option takes arguments, so it is strange that :private-members: doesn't.

Instead you can use autodata:

.. automodule:: yourmodule
   :members:

.. autodata:: yourmodule._PRIVATE_ATTR

Here is a slightly different alternative with autodata "inside of" automodule:

.. automodule:: yourmodule
   :members:

   .. autodata:: _PRIVATE_ATTR

There is also an autoattribute directive but it does not work with module-level "data members". I have found that autoattribute can be used to document private class attributes, but the documentation is not clear on the exact difference between autodata and autoattribute.