python - 狮身人面像 : Link to a method of a class in another module in Python docstring

Question

我想在一个模块(比如 module_2.py)的另一个方法中添加一个链接到一个类的方法(比如 module_1.py) .我希望链接在 Sphinx 中有效。

假设:

module_1.py

class ABC:
   def foo(self):
      """
      See docstring of module_2.py bar():<link to bar() in module_2.py>
      """
      print("foo")

module_2.py

class XYZ:
    def bar(self):
    """
    This function prints hello.
    """
    print("hello")

Answer 1

要真正获得超链接，您的方法引用需要包含完整路径。创建任何链接的最简单方法是使用 :obj:交叉引用:

"""See docstring of :obj:`path.to.module_2.XYZ.bar`."""

See docstring of path.to.module_2.XYZ.bar.

您可以使用 tild ~ 将 anchor 文本缩短到路径的最后一个元素。 :

"""See docstring of :obj:`~path.to.module_2.XYZ.bar`."""

See docstring of bar.

或指定custom text像这样:

"""See docstring of :obj:`XYZ.bar <path.to.module_2.XYZ.bar>`."""

See docstring of XYZ.bar.

这可能是对读者最友好的解决方案。

为了完整起见，请注意 :obj: 是一个通用的无类型引用，但 Sphinx 提供了 several other categories of cross-reference具有一些特定的行为。