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

Question

例如，我有以下代码：

# 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类文档？

Answer 1

您可以使用intersphinx来实现这一点。

1. 将以下行添加到conf.py：

extensions = "sphinx.ext.intersphinx“#或编辑现有的'extensions‘列表intersphinx_mapping = {'numpy'：('http://docs.scipy.org/doc/numpy/'，None)}

• 在文档字符串中使用此reST标记：

:param p:要由二次函数近似的多项式。：类型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目标。

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

Answer 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
"""

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