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

相关文章