Sphinx：链接到 Python 文档字符串中另一个模块中的类的方法

Question

我想在另一个模块（比如说module_2.py）的另一个方法中添加一个指向一个模块（比如说）中的类的方法的链接module_1.py。我希望链接在 Sphinx 中工作。

认为：

模块_1.py

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

模块_2.py

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

Answer 1

你可以写：

class ABC:
  def foo(self):
    """
    See docstring of :py:meth:`bar() <XYZ.bar>` in :py:mod:`module_2`.
    """
    print("foo")

显示的标记使用角色链接到文档元素。如果 Python 是文档的默认域，则:py可以省略。角色meth链接到方法名称。可以使用带点的名称。同样，mod链接到模块名称。角色的内容写成ween ``。内容（逻辑链接名称可以有不同的视觉内容。因此逻辑链接名称写在<>. 示例：:role:`text <logical name>`.

更多信息：http : //www.sphinx-doc.org/en/stable/domains.html#role-py : meth

Answer 2

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

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

请参阅 .doc 的文档字符串path.to.module_2.XYZ.bar。

您可以使用波浪号~将锚文本缩短为路径的最后一个元素：

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

请参阅 .doc 的文档字符串bar。

或者像这样指定自定义文本：

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

请参阅 .doc 的文档字符串XYZ.bar。

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

为了完整:obj:起见，请注意这是一个通用的无类型引用，但 Sphinx 提供了其他几种具有某些特定行为的交叉引用类别。