Python中的reStructuredText链接

Question

If I have the following function in Python:

def _add_parameter(self, a):
    # do something

And I want to add a docstring to link to the above function using reStructuredText, I just need to add an underscore at the end of the function name like the following:

"""
The _add_parameter_ adds parameters.
"""

But instead of linking it to the function, I get a cannot find declaration to go to warning. How do I fix this?

Answer 1

The autodoc extension only documents non private members, ie members where the name does not start with an underscore. From the documentation:

.. autoclass:: Noodle
       :members:
    will document all non-private member functions and properties (that is,
    those whose name doesn’t start with _).

So, when autodoc tries to find the place to link to, it doesn't find it.

To override not documenting private members you can use :private-members: , but I cannot tell from experience if that works.However, it is generally preferred to only document the public interface.

Answer 2

Since the formatting of the comments made me confused, here it is with proper formatting:

class A:
    def foo(): ...

def bar(): ...

"""
:py:meth:`A.foo`
:py:func:`bar`
"""