如何链接到使用Sphinx的str方法？

Question

我正在使用Sphinx从我的docstrings中生成我的HTML文档，比如一个好的'Pythonista'。

我有一个文档字符串看起来像这样：

def do_a_thing(text): 
    ''' 
    Call the ``str.strip()`` method on ``text``. Then do something 
    else with it. 
    ''' 

不过，我希望它链接到https://docs.python.org/3/library/stdtypes.html#str.strip，而不是仅仅将所有的等宽字体和代码块状。

我试过几个途径：这些工作

:py:func:`str.strip()` 
:mod:`str.strip()` 
:class:`str.strip()` 
:any:`str.strip()` 
:doc:`str.strip()` 

无 - 或者更准确地说，前四个办法给我等宽&加粗字体，但它们都没有实际联系的任何地方。而any指令给我WARNING: 'any' reference target not found: str.strip()

显然我可以自己建立一个链接，但这看起来很严重，也可能并不完全是我想要的，因为当我升级到Python 4时呢？然后，我必须更新我的文档中的所有链接，这很糟糕。

链接到str方法的Python文档的正确方法是什么？

Answer 1

Intersphinx ftw！

在conf.py，添加几行。金字塔文档有很好的例子来添加Intersphinx extension和configuring intersphinx mappings。

extensions = [ 
    # ... 
    'sphinx.ext.intersphinx', 
    # ... 
    ] 

和

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

然后在你的.rst文件，有几种方法来指向Python文档。我们更愿意使用以下格式，它向文档作者指出链接将解析为指定的外部文档源。

:mod:`venv module <python:venv>` 
:ref:`package <python:tut-packages>` 

对于Python，你也可以使用任何指令的Python Domain内，其中包括：

:py:meth:`str.strip` 

至于版本，你可以在你intersphinx映射使用多个名称或更新目标映射。

intersphinx_mapping = { 
    #... 
    'python2': ('https://docs.python.org/2', None), 
    'python': ('https://docs.python.org/3', None), # use "python" for default version 
    #... 
} 

或在未来...

intersphinx_mapping = { 
    #... 
    'python2': ('https://docs.python.org/2', None), 
    'python3': ('https://docs.python.org/3', None), 
    'python': ('https://docs.python.org/4', None), # use "python" for default version 
    #... 
}