在 Sphinx 中交叉引用 Python 对象有什么要求？答案

【问题标题】：What requirements are there for cross-referencing a Python object in Sphinx?在 Sphinx 中交叉引用 Python 对象有什么要求？
【发布时间】：2021-07-26 10:11:18
【问题描述】：

我正在使用 :class: 并收到很多警告

WARNING: py:class reference target not found: mypkg.submodule.class.

我在文档中的任何地方都找不到正确交叉引用的确切要求。

这是我认为目前不完整的要求列表：

对象的模块需要是可导入的
对象需要存在于模块内部
需要使用:py:class::、:py:func:: 或类似指令在构建中的其他位置记录该对象
- 此指令可由autodoc 扩展生成，在这种情况下，对象需要有一个与之关联的文档字符串。

【问题讨论】：

标签： python python-sphinx autodoc cross-reference

【解决方案1】：

对于要交叉引用的内容，必须首先“声明”。

Python 域（名称 py）为模块 declarations 提供以下指令：

有两种情况需要考虑：

domain directives (.. domain:directive_name::) 和
roles (:domain:role_name:)。

您指定的:class: 的大小写实际上是编写角色:py:class: 的缩写语法，不要与指令声明 .. py:class:: 混淆。

该指令可以由 autodoc 扩展生成，在这种情况下，对象需要有一个与之关联的文档字符串。

指令声明由 autodoc 隐式完成，但对于要由 autodoc 声明的没有文档字符串的对象，您必须使用 :undoc-members: option with the autodoc directives。

没有文档字符串的成员将被排除在外，除非您提供 undoc-members 标志选项：
.. automodule:: noodle    
   :members:    
   :undoc-members: 

声明一个对象的一个效果是它被插入到索引中。因此，您可以检查索引以确保它已被声明和插入。（但请注意，labels used in referencing arbitrary locations 不会插入索引中。）

【讨论】：

@RobinDeSchepper 默认在您的主页（通常是 index.html 对应于 index.rst）上有一个名为 index 的链接，Sphinx 会自动为您生成和管理。