reStructuredText link in Python

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?

Are you using Sphinx? Then see http://www.sphinx-doc.org/en/stable/domains.html — jonrsharpe, Aug 15 '16 at 08:30
Yes, I am using Sphinx. So according to your link I should do :py:func:`_add_parameter` ? — Sajid, Aug 15 '16 at 09:42
It's a method, so probably `:py:meth:~ClassName.method_name`, but have a go and see what works — jonrsharpe, Aug 15 '16 at 09:50

score 1 · Answer 1 · answered Aug 15 '16 at 15:41

The autodoc extension only documents non private members, i.e. 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.

score 0 · Answer 2 · answered Jul 11 '22 at 18:29

0

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`
"""

answered Jul 11 '22 at 18:29

Minek Po1

142
1
9

reStructuredText link in Python

2 Answers2