Python ReST 文档字符串中是否有类似 C# 的 "see cref" 的内容？

Question

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

这些摘要引用 class 名称作为 <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 吗？）如您所见，我只是将 class 名称和参数名称作为纯文本输入，不知道在以后创建 Web 文档时是否有这种特殊语法可以从中创建可点击链接。

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

Answer 1

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

:py:class:`ClassName`

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

我不知道 file_name 有任何类似的方法。但是为了什么你需要一个可点击的 link 到下面的拖车线？

我使用这个 rtype 指令。

Python ReST 文档字符串中是否有类似 C# 的 "see cref" 的内容？

Is there something like C#'s "see cref" in Python ReST docstrings?

c#

python

restructuredtext

docstring

python-3.x