如何 link 通过 sphinx 在 Python 3 文档中键入 contextmanager 标签

Question

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

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

...
std:label
    23acks                    Acknowledgements             : whatsnew/2.3.html#acks
    23section-other           Other Changes and Fixes      : whatsnew/2.3.html#section-other
...
    typebytearray             Bytearray Objects            : library/stdtypes.html#typebytearray
    typebytes                 Bytes Objects                : library/stdtypes.html#typebytes
    typecontextmanager        Context Manager Types        : library/stdtypes.html#typecontextmanager
    typeiter                  Iterator Types               : library/stdtypes.html#typeiter
    typememoryview            Memory Views                 : 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 替换，但没有 link.

我错过了什么？

我在 Python 3.6.2

的 Anaconda 安装上使用 sphinx 1.6.3

注一

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

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

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

注2

可能不是 100% 相关，但我可以在同一部分 link 到 :py:meth:`~contextmanager.__enter__` 没有任何问题。

Answer 1

这些都适合我。

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

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

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

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

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

如何 link 通过 sphinx 在 Python 3 文档中键入 contextmanager 标签

How to link to typecontextmanager label in Python 3 docs via sphinx

python

restructuredtext

python-sphinx