Как задокументировать отдельный приватный атрибут с помощью автодока Sphinx?

Question

Я использую sphinx и расширение autodoc для автоматического создания документации из строк документации в моих модулях python.

Я в настоящее время использую automodule директива для документирования всех открытых членов модуля

.. automodule::
    :members:

Мой модуль также имеет ряд личных атрибутов. Я хотел бы включить один из них в документацию.

Есть ли способ сказать automodule документировать всех открытых участников, а также этого частного участника? Я пытался использовать :private-members: вариант, но это включает в себя все частные члены. Я также попытался вручную указать атрибут private, но затем он не задокументировал ни одного из открытых членов.

.. automodule::
    :members: _PRIVATE_ATTR

Я хотел бы избежать необходимости вручную перечислять каждого публичного участника, просто чтобы добавить этого частного участника.

Есть ли способ сделать это с Autodoc?

Answer 1

Вот то, что я ожидал бы работать (протестировано с Sphinx 1.8.3):

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

Но это не совсем работает. Если :private-members: Опция дается, с аргументами или без, все частные члены включены (при условии, что у них есть строка документации).

:special-members: опция принимает аргументы, поэтому странно, что :private-members: не делает.

Вместо этого вы можете использовать autodata:

.. automodule:: yourmodule
   :members:

.. autodata:: yourmodule._PRIVATE_ATTR

Вот немного другая альтернатива с autodata "Внутри" automodule:

.. automodule:: yourmodule
   :members:

   .. autodata:: _PRIVATE_ATTR

Также есть autoattribute директива, но она не работает с "членами данных" уровня модуля. Я обнаружил, что autoattribute может использоваться для документирования атрибутов частного класса, но документация не дает четкого представления о точной разнице между autodata а также autoattribute,