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

编程问答 2022-08-10

问题描述

我正在使用AttributeError: 'Series' object has no attribute 'CATEGORIA_DE_RISCO' 并收到很多警告

:class:。

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

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

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

解决方法

要进行交叉引用，必须先“声明” 。

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

有2种情况需要考虑：

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

此伪指令可以由autodoc扩展名生成，在这种情况下，对象需要具有与其关联的docstring。

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

没有文档字符串的成员将被忽略，除非您给undoc-members标志选项：

.. automodule:: noodle    
   :members:    
   :undoc-members:

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

autodoccross-referencepythonpython-sphinx