如何使用 sphinx-autodoc 引用字典？

Question

:data:`~package._module._DICT_NAME`

不起作用，_DICT_NAME 呈现为好像被引用，但没有超链接。与 :obj: 相同。将它放在一个函数中不是一个可接受的解决方法。

最小conf.py:

extensions = ['sphinx.ext.autodoc']
templates_path = ['_templates']
exclude_patterns = []
html_static_path = ['_static']

def skip(app, what, name, obj, would_skip, options):
    if name.startswith('_'):  # include private methods
        return False
    return would_skip

def setup(app):
    app.connect("autodoc-skip-member", skip)

（实际上下文：conf.py, attempted cross-reference, the dict, rendered docs（向上滚动一点））

Answer 1

在尝试引用 _DICT_NAME 之前，请验证它是否已放入通用索引中（因此可以交叉引用！！）。如果使用不带 :undoc-members: 选项的 autodoc 指令，如果字典没有注释，则不会包含该字典。变量不能有文档字符串，因此您需要在 py 之前或之后立即使用注释 #: 以便 autodoc 获取它。

除非您明确将 .rst 中的字典包含在 py:data:, using Domains and roles. Or, by including it in the .rst (using autodata or autoattribute 中，以防您的 automodule 或 autoclass 没有选择它而您使用 autodoc 扩展的指令。

那么你的_DICT_NAME也是一个私有变量，所以如果你使用的是Sphinx Napoleon扩展，你需要检查conf.py设置看它是否像napoleon_include_private_with_doc = True一样被包含.

_DICT_NAME is rendered as if referenced, but no hyperlink.

首先检查它是否显示在您文档的最终呈现中，无论是 HTML 还是其他。如果它被包含并且有注释，那么它可以被交叉引用并且将生成 link。

How to reference a dict with sphinx-autodoc?

请注意，您没有使用 autodoc 进行引用。 Autodoc 正在提取您在 .rst 中编写其指令的文档字符串。您的 :data: 交叉引用是按域和角色完成的。尽管您可以在您的文档字符串中引用，然后由 autodoc 提取并最终由 Sphinx 工具一起呈现。

OP 添加 MCVE 后编辑：

我看到的第一个问题是，您的字典 _DEFAULT_TRAINGEN_CFG 在模块 _default_configs.py...

中

所以，你写的交叉引用应该是正确的 :data:~deeptrain.util._default_configs._DEFAULT_TRAINGEN_CFG\...但是，你真的在任何 .rst 文件中包含这个模块吗？我不这么认为，查看 deeptrain.util.rst _default_configs.py 模块不存在于任何 automodule 指令中，所以没有什么可参考的（这就是为什么 hyperlink 不是' t生成)...

交叉引用的三个例子：

模块级字典，dict_document.py

#: a comment on your dictionary
_DEFAULT_TRAINGEN_CFG = dict(
    dynamic_predict_threshold_min_max = None,
    checkpoints_overwrite_duplicates  = True,
)

一个可能dict_document.rst

dic_document module
===================

.. automodule:: dict_document

some text to break, lets reference:

:data:`_DEFAULT_TRAINGEN_CFG` WORKS !!

结果：

另一种可能dict_document.rst

dic_document module
===================
Lets try a more explicit apporach:

.. automodule:: dict_document
    :exclude-members: _DEFAULT_TRAINGEN_CFG

    .. autodata:: _DEFAULT_TRAINGEN_CFG

some text to break, lets reference:

:data:`_DEFAULT_TRAINGEN_CFG` WORKS !!

结果：

还有一个可能dict_document.rst

dic_document module
===================

Lets try without using autodoc:

.. py:module:: Sphinx_test.dict_document

.. py:data:: _DEFAULT_TRAINGEN_CFG
    :type: dict[str, Any]

Notice the docstring wasn't extracted from .py and included here because autodoc directives weren't used.

some text to break, lets reference:

:py:data:`~._DEFAULT_TRAINGEN_CFG` WORKS !!

结果：

最小示例，不修改.rst，在module.py；注意评论可以为空：

#:
some_dict = {"a": 1}

一些文档字符串：

"""
:data:module.some_dict
"""

如何使用 sphinx-autodoc 引用字典？

How to reference a dict with sphinx-autodoc?

restructuredtext

cross-reference

python-sphinx

autodoc