How do I refer to classes and methods in other files my project with Sphinx?

Question

I'm trying to write Sphinx docstrings that link to some classes and methods in other parts of my package, but can't figure out how to construct these links or get them to display as I need them to.

I have

# a.py

from .b import *

class A(object):

    def func_one():
        """Does stuff using `func_two` from `B`."""
        some_b = B ...
        some_b.func_two()
        # ...

and

# b.py

class B(object):

    def func_two():
        # ...

where my package is organized

my_package/
    a.py
    b.py

and I want the Sphinx docs for A.func_one to display as

Does stuff using func_two from B.

and to contain links to func_two and B.

I've tried various combinations of the full names of the method and class, but non seem to work. How do I accomplish this?

Answer 1

To create cross-references to Python objects, use the roles (:class:, :meth:, etc.) provided by the Python domain. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects.

Example:

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

To get the link text to be only the last part of the target, use a ~ (tilde) prefix. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-syntax.

Example:

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