如何在 Sphinx 中交叉引用 autodoc 生成的函数？

Posted 2023-02-24

【中文标题】如何在 Sphinx 中交叉引用 autodoc 生成的函数？

【英文标题】：How would I cross-reference a function generated by autodoc in Sphinx?

【发布时间】：2014-05-07 04:38:18

【问题描述】：

我正在使用 Sphinx autodoc 功能根据我的 Python 库的文档字符串生成文档。

交叉引用的语法找到here

标签必须在该部分之前，以允许从文档的其他区域引用该部分。

我有一个 .rst (ReStructeredText) 文件，用于我的一个类。它使用

.. autoclass:: classname
    :members:

为类生成文档。

我的问题是，如何从文档中的另一个 .rst 文档中引用该类的自动生成方法？如果我尝试在方法的文档字符串中放置标签，Sphinx 会抱怨。如果我尝试在方法标题之前放置标签，Sphinx 将无法识别它。

有没有一种简单的方法可以做到这一点，还是我必须在我的类文件中显式写入方法名称并在其前面加上标签？

这是 [Python 文档2 中的一个参考示例，做我需要的事情（我假设它使用了自动文档功能，尽管我不确定）

【问题讨论】：

标题询问函数，正文和回答询问方法。我希望有一个引用 .. autofunction:: 的答案，但可惜它不在这里。

【参考方案1】：

除了已经提供的excellent answer：

要为引用的模块（方法、函数、属性等）添加别名，使用以下语法：

:mod:`Alias Name <package.module>`

这将在文档中显示为对 Alias Name 的引用，并链接到提供的模块。

【参考方案2】：

您无需添加标签。要引用 Python 类、方法或其他文档化对象，请使用 Python domain 提供的标记。

例如，下面定义了对mymethod方法的交叉引用：

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

甚至更简单（因为 Python 域是默认的）：

:meth:`mymodule.MyClass.mymethod`

您在问题中链接到的TextWrapper.wrap 的文档包括两个此类交叉引用（单击“显示源代码”以查看 reST 标记）。

【讨论】：

和:mod:… 用于模块。

和:func:… 用于功能。如何交叉引用 Python 角色的完整列表是 here。

如果其他模块托管在 readthedocs 上，这只会偶然起作用。如果它托管在其他地方（这很可能发生在任何具有本机代码依赖项的情况下，因为它们不可能托管在 readthedocs 上），这不是一个解决方案。

@wvxvw。你在说什么？使用 intersphinx，如果您需要将域设置为 py 以外的其他内容，请执行此操作。但基本方法效果很好。

@MadPhysicist 如果“意外”对您来说没问题，那么继续使用它......有什么问题？