如何鏈接到使用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 
    #... 
}