如何自动链接到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.Polynomialnumpy.polynomial.Polynomial

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()函数文档到文档的超链接(带有"Polynomial"文本)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.

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插件结合使用。