4

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?

Brendan Abel
  • 35,343
  • 14
  • 88
  • 118
  • Could you give some context - *why* do you want to document one of the private members? Could that documentation live at the class/module level, or could you make it public, or ...? – jonrsharpe Jan 31 '19 at 18:02
  • @jonrsharpe Private members sometimes are useful in the documentation. I can put the documentation for the private attr in the module docstring, but that means it would be documented differently from the rest of the attributes and classes (i.e. inline) and it will have inconsistent ordering in the rendered docs. Considering :private-members: is an option, it doesn't seem like an unrealistic expectation to be able to document a subset of private members. I shouldn't have to change the API just to get documentation to render correctly. – Brendan Abel Jan 31 '19 at 18:07
  • Well, it seems sphinx doesn't support it officially. Or you should be able to do `:private-members: _what_you_want`. – Sraw Jan 31 '19 at 18:20
  • @jonrsharpe __builtin__ dunders and sunders are in python documentation. Same with C# and Java API's exposing internals that reflect on the externals...Was that a rhetorical question? – bad_coder Jan 06 '20 at 05:21

1 Answers1

5

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.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • I think the difference is exactly how you said. `autodata` is for module members while `autoattribute` is for class members. [According the the sphinx docs](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoattribute) "For module data members and class attributes" – Jacob Pavlock Jul 27 '20 at 19:57