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

Question

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

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

我在文档中找不到正确交叉引用的具体要求

这是一份不完整的需求清单，我认为有：

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

Answer 1

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

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

有两种情况需要考虑：

• domain directives（.. domain:directive_name::）和
• roles（:domain:role_name:）

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

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

指令声明由autodoc隐式完成，但对于没有由autodoc声明的DocString的对象，必须使用^{} 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未插入索引。）