Question

我正在使用Sphinx从我的文档字符串生成我的HTML文档，就像一个很好的'Python'。

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

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()`

这些都不起作用 - 或者更确切地说，前四种方法给我一个等宽的＆amp;粗体字体，但没有一个实际链接到任何地方。 any指令给了我WARNING: 'any' reference target not found: str.strip()

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

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

Answer 1

Intersphinx ftw！

在conf.py中，添加几行。 Pyramid文档提供了添加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
    #...
}

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

1 个答案: