Как автоматически связать тип параметра в строках документации ReST в Sphinx?

Например, у меня есть следующий код:

# 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
person Kit    schedule 15.02.2014    source источник

Ответы (2)


arrow_upward
10
arrow_downward

Для этого вы можете использовать intersphinx.

  1. Добавьте эти строки в conf.py:

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

  2. Используйте эту разметку 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). Последняя форма показана в справочной документации и доступна как интерсфинкс-мишень.

Если вы хотите, чтобы текст ссылки был полным именем класса, удалите символ тильды (~). Подробнее о «списках информационных полей» см. http://sphinx-doc.org/domains.html. " и перекрестные ссылки на объекты Python.

person mzjn    schedule 25.02.2014

arrow_upward
3
arrow_downward

Вы используете две разные директивы для описания и типа.

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

person davidism    schedule 15.02.2014