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

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.