How use :private-members: to show mangled member value constants in Sphinx

问题

How can I get the value of a constant into my Sphinx documentation?

.. automodule:: mymodule
  :members:
  :private-members:

This is my test module:

class Test:
  """My Test Class"""

  __MY_TEST_CONSTANT = 98.2
  """My test constant docu"""

At the moment I get the description of my private constant but the value is "None" and not "98.2".

class Test: 
  My Test Class


  __MY_TEST_CONSTANT = None
  My test constant docu

回答1:

I tested this and I'm pretty sure it's either: an undocumented feature, a bug, or both. For example,

your_module.py

class YourClass:
    """Your class."""

    _one_cls = 11.1  #: one class
    __two_cls = 22.2  #: two class
    __three_cls__ = 33.3  #: three class
    four_cls_ = 44.4  #: four class

your_module.rst

your_module
===========

.. automodule:: your_module
    :members:
    :undoc-members:
    :show-inheritance:
    :private-members:

results in having both "mangled" _YourClass__two_cls and " not mangled" __two_cls, however only the "mangled" member has the value.

Now lets try documenting each object individually using sphinx directives:

your_module.rst

your_module
===========

.. automodule:: your_module
    :exclude-members: YourClass

    .. autoclass:: YourClass
      :members: 
      :show-inheritance:
      :private-members: 
      :exclude-members: _one_cls, four_cls_, __two_cls, _YourClass__two_cls

        .. autoattribute:: _one_cls

        .. autoattribute:: _YourClass__two_cls

        ..
            including this would yield an error:
            .. autoattribute:: __two_cls
            > failed to import attribute 'YourClass.__two_cls' from module 'your_module'

        .. autoattribute:: four_cls_

results in:

Here 2 noteworthy aspects can be verified that hint at a bug.

By explicitly including the "mangled" _YourClass__two_cls the HTML is different from the first version, now it gets "wrapped" in a blockquote and because of that the indent also shows differently.
If you try to explicitly the .. autoattribute:: __two_cls Sphinx issues the following warning:

WARNING: autodoc: failed to import attribute 'YourClass.__two_cls' from module 'your_module'; the following exception was raised: Traceback (most recent call last): File "===========\lib\site-packages\sphinx\util\inspect.py", line 307, in safe_getattr return getattr(obj, name, *defargs) AttributeError: type object 'YourClass' has no attribute '__two_cls'

Because Sphinx imports the Python objects the member __two_cls' will already be "mangled" before the document generation step starts. Sphinx is actually correct in this, documenting the "not mangled" member would lead documentation readers to a false expectation.

来源：https://stackoverflow.com/questions/61120996/how-use-private-members-to-show-mangled-member-value-constants-in-sphinx

标签

python

python-sphinx

private-members

autodoc

double-underscore