如何通过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 。 结果显示，其中包括：

...
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正是我要寻找的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

根据清单行，使用:ref:`with <python:with>` ，我应该: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％相关，但是我可以在同一部分中链接到:py:meth:`~contextmanager.__enter__` ，没有任何问题。

Answer 1

这些都对我有用。

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

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

它们为我呈现的方式如下：

• 上下文管理器类型
• typecontextmanager

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

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