如何在 Sphinx 中自动链接到 ReST 文档字符串中的参数类型？答案

【问题标题】：How do I automatically link to a parameter type in ReST docstrings in Sphinx?如何在 Sphinx 中自动链接到 ReST 文档字符串中的参数类型？
【发布时间】：2014-02-15 15:28:38
【问题描述】：

例如，我有以下代码：

# Solve for coefficients of quadratic approximation
def quad(p, x):
    """Solves for the coefficients of the quadratic approximation of a
    polynomial ``p`` at points ``x``.

    :param :cls:`numpy.polynomial.Polynomial` p:
        The polynomial to be approximated by a quadratic function.
    :param list x:
        The three points along which the quadratic function is to be fitted.
    """

注意我说:cls:numpy.polynomial.Polynomial 的部分。如何将该链接直接链接到 numpy.polynomial.Polynomial 类的文档？

【问题讨论】：

标签： python numpy python-sphinx docstring

【解决方案1】：

您可以为此使用intersphinx。

将这些行添加到 conf.py：

extensions = ["sphinx.ext.intersphinx"]        # Or edit existing 'extensions' list
intersphinx_mapping = {'numpy': ('http://docs.scipy.org/doc/numpy/', None)}

在文档字符串中使用这个 reST 标记：

:param p: The polynomial to be approximated by a quadratic function.
:type p: :class:`~numpy:numpy.polynomial.polynomial.Polynomial`

这将导致从您的 quad() 函数的文档到 numpy.polynomial.polynomial.Polynomial 的文档的超链接（带有文本“多项式”）。

numpy.polynomial.Polynomial 和numpy.polynomial.polynomial.Polynomial 可以互换使用（请参阅http://docs.scipy.org/doc/numpy/reference/routines.polynomials.classes.html#basics）。后一种形式是参考文档中显示的形式，可用作 intersphinx 目标。

如果您希望链接文本是完全限定的类名，请删除波浪号 (~) 字符。有关“信息字段列表”和对 Python 对象的交叉引用的更多信息，请参阅 http://sphinx-doc.org/domains.html。

【讨论】：

【解决方案2】：

您对描述和类型使用两个不同的指令。

"""
...
:param p: The polynomial to be approximated by a quadratic function.
:type p: numpy.polynomial.Polynomial
...
:return: description of return value
:rtype: type of return value
"""

您还可以将 Python 3 注释与 sphinx-autodoc-annotation 插件一起使用。

【讨论】：