Python ReST 文档字符串中是否有类似 C# 的“查看 cref”的内容？

Question

我正在将一些 C# 代码转换为 Python 3，包括通常在原始 C# 代码中以 XML 摘要形式编写的文档。

这些摘要引用类名作为 <see cref="ClassName"/> 元素或 <paramref name="fileName"/> 元素引用参数，例如在将其转换为 HTML 时创建可点击的链接。我想知道我使用的 Python ReST 文档字符串格式中是否有类似的东西。

以这个 C# 方法文档为例：

/// <summary>
/// Reads and returns a <see cref="DummyFile"/> instance from the file with the
/// given <paramref name="fileName"/>.
/// </summary>
/// <param name="fileName">The name of the file to read the data from.</param>
/// <returns>The read <see cref="DummyFile"/> instance.</returns>
public DummyFile LoadDummyFile(string fileName)
{
    // Do some dummy file work.
}

在 Python 中，我会将其转换为：

"""
Reads and returns a DummyFile instance from the file with the given file_name.
:param file_name: The name of the file to read the data from.
:param str file_name: The name of the file to read the data from.
:return: The read DummyFile instance.
:rtype: DummyFile
"""
def load_dummy_file(file_name: str) -> DummyFile
    # Do some dummy file work.

（有人甚至使用:rtype吗？） 如您所见，我只是以纯文本形式输入了类名和参数名，不知道以后创建 Web 文档时是否有这样的特殊语法可以从中创建可点击的链接。

是否可以在 ReST 文档字符串中创建此类引用，如果可以，它们可能的语法是什么（希望比 C# 更短）？

Answer 1

对于<see cref="ClassName">，您可以使用

:py:class:`类名`

这将成为类定义的可点击引用。见Sphinx Domains。

我不知道文件名的任何类似方法。但是你需要一个可点击的链接到下面的地方拖线吗？

我使用这个 rtype 指令。