在Sphinx中交叉引用Python对象有哪些要求？

问题描述

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

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

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

这是我认为有以下要求的不完整列表：

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

---

解决方案

要进行交叉引用，必须首先声明

。

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不会插入到索引中。)