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

Question

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

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

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

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

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

Answer 1

要成为cross-referenced，必须先“声明”。

The Python domain (name py) provides the following directives for module declarations:

有两种情况需要考虑：

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

你指定的:class:大小写实际上是写角色:py:class:的缩写语法，不要和指令declaration[=15混淆了=].

This directive can be generated by the autodoc extension, in which case the object needs to have a docstring associated to it.

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

Members without docstrings will be left out, unless you give the undoc-members flag option:
.. automodule:: noodle    
   :members:    
   :undoc-members: 

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

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

What requirements are there for cross-referencing a Python object in Sphinx?

python

cross-reference

python-sphinx

autodoc