How would I cross-reference a function generated by autodoc in Sphinx?

Question

I am using the Sphinx autodoc feature to generate documentation based on the docstrings of my Python library.

The syntax for cross referencing is found here

A label must precede the section in order to allow that section to be referenced from other areas of the documentation.

What I have is a .rst (ReStructeredText) file for one of my classes. It uses

.. autoclass:: classname
    :members:

To generate documentation for the class.

My question is, how would I reference the auto-generated methods of the class from another .rst document in the documentation? If I try to place a label within the method's docstring, Sphinx complains. If I try to place a label before the method heading, Sphinx doesn't recognize it.

Is there a simple way to do this, or will I have to explicitly write in my class file the method name and precede that with a label?

Here is an example a reference within the [Python documentation2 doing what I need (I am assuming it used the autodoc feature, though I don't know for sure)

Solution 1

You don't need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain.

For example, the following defines a cross-reference to the mymethod method:

:py:meth:`mymodule.MyClass.mymethod`

Or even simpler (since the Python domain is the default):

:meth:`mymodule.MyClass.mymethod`

The documentation of TextWrapper.wrap that you link to in the question includes two cross-references of this kind (click on "Show Source" to see the reST markup).

Solution 2

In addition to the excellent answer already provided:

To add an alias to the referenced module (method, function, attribute, etc.), the following syntax is used:

:mod:`Alias Name <package.module>`

This will appear as a reference to Alias Name in the docs, and link to the module provided.

Comments

[Gringo Suave]

And :mod:… for modules.

[JFlo]

And :func:… for functions. A complete list of how to cross-reference Python roles is here.

[wvxvw]

This will only work by accident, if the other module is hosted on readthedocs. If it's hosted elsewhere (which is very likely to happen for anything that has native code dependencies, as those are impossible to host on readthedocs), that's not a solution.

[Mad Physicist]

@wvxvw. What are you talking about? Use intersphinx and if you need to set the domain to something other than py, do so. But the basic method works fine.

[wvxvw]

@MadPhysicist If "by accident" is fine for you, then go ahead and use it... what's the problem?

[Mad Physicist]

@wvxvw. It's not ok. I'm trying to figure out why you're saying it's an accident. It doesn't look like one to me. I've successfully linked to python, numpy and matplotlib, which aren't hosted on rtd...

[wvxvw]

In order for intersphinx to work the party that's hosting the documentation needs to make provisions for that. Some do. Some don't. In my experience, this method is unreliable (and there isn't, in principle, a reliable way, at least not using Sphinx to do this).

[OrenIshShalom]

note that when reference is inside the same class, no need for the mymodule.myclass prefix