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。

将这些行添加到conf.py：

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

在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。

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插件一起使用。

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

2 个答案: