如何在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类的文档？

- Kit

Answer 1

你可以使用 intersphinx 来实现此功能。

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

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

2. 在docstring中使用这个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文档的超链接（文本为“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。

- mzjn

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

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

- davidism