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
...

粗体网址正是我要找的，因为我的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>`下），使用std:label我应该指向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>`

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

以下是他们为我呈现的方式：

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

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

如何通过sphinx

1 个答案: