如何通过 sphinx 链接到 Python 3 文档中的 typecontextmanager 标签

Question

我正在尝试在我的一份 reST 文档中引用以下链接：https://docs.python.org/3/library/stdtypes.html#typecontextmanager。我正在尝试使用 :ref: 内联指令而不是链接。

我跑了python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv。结果显示，除其他外：

... 标准：标签 23acks 致谢：whatsnew/2.3.html#acks 23section-other 其他更改和修复：whatsnew/2.3.html#section-other ... typebytearray 字节数组对象：库/stdtypes.html#typebytearray typebytes 字节对象：库/stdtypes.html#typebytes typecontextmanager 上下文管理器类型：library/stdtypes.html#typecontextmanager typeiter 迭代器类型：library/stdtypes.html#typeiter typememoryview 内存视图：library/stdtypes.html#typememoryview ...

加粗的 URL 正是我正在寻找的，因为我的 intersphinx_mapping 看起来像这样：

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

我使用以下指令：

:ref:`context manager <python:typecontextmanager>`

这似乎指向正确的标签，但我收到以下警告：

WARNING: undefined label: python:typecontextmanager (if the link has no caption the label must precede a section header)

:ref: 被字符串 context manager 替换，但没有链接。

我错过了什么？

我在 Python 3.6.2 的 Anaconda 安装上使用 sphinx 1.6.3

注 1

根据库存行（也在std:label下），我使用:ref:`with <python:with>`也有同样的问题，它应该指向https://docs.python.org/3/reference/compound_stmts.html#with：

     with                       The with statement          : reference/compound_stmts.html#with

我猜主要问题的解决方案很可能也能解决这个问题。

注2

可能不是 100% 相关，但我可以毫无问题地链接到同一部分中的 :py:meth:`~contextmanager.__enter__`。

Answer 1

这些都适合我。

:ref:`python:typecontextmanager`
:ref:`typecontextmanager <python:typecontextmanager>`

请注意，如果您在目标周围使用尖括号，则必须包含标题。

这是它们为我呈现的方式：

• Context Manager Types
• typecontextmanager

顺便说一句，我最近在 Pyramid 的 Glossary 文档中添加了上下文管理器，我认为这很好地解释了它们是什么。这是reST来源：

:ref:`With Statement Context Managers <python:context-managers>`
:ref:`with <python:with>`