相关疑难解决方法(0)

如何使用Python的文档字符串记录带参数的方法？

编辑: PEP 257给出了这个例子:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

这是大多数Python开发人员使用的约定吗？

Keyword arguments:
<parameter name> -- Definition (default value if any)

我期待一些更正式的东西,比如

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real …

我正在尝试将外部API的交叉引用添加到我的文档中,但我面临三种不同的行为.

我正在使用sphinx(1.3.1)和Python(2.7.3),我的intersphinx映射配置为:

{
'python': ('https://docs.python.org/2.7', None),
'numpy': ('http://docs.scipy.org/doc/numpy/', None),
'cv2' : ('http://docs.opencv.org/2.4/', None),
'h5py' : ('http://docs.h5py.org/en/latest/', None)
}

我可以毫不费力地编写numpy API的交叉引用,:class:`numpy.ndarray`或者:func:`numpy.array`像我们预期的那样给我一些像numpy.ndarray这样的东西.

但是,使用h5py,我可以生成链接的唯一方法是省略模块名称.例如,:class:`Group`(或:class:`h5py:Group`)给我Group但:class:`h5py.Group`无法生成链接.

最后,我找不到一种方法来编写一个工作交叉引用OpenCV API,这些似乎都没有工作:

:func:`cv2.convertScaleAbs`
:func:`cv2:cv2.convertScaleAbs`
:func:`cv2:convertScaleAbs`
:func:`convertScaleAbs`

如何正确编写对外部API的交叉引用,或配置intersphinx,以便在numpy情况下生成链接？

我正在尝试清理我的python代码文档,并决定使用sphinx-doc,因为它看起来不错.我喜欢如何使用以下标签引用其他类和方法:

:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function

我试图弄清楚如何在函数中记录参数名称,所以如果我有一个像这样的函数:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something?:`parameter1` And then describe the parameter.

   """

这是最好的做法是什么？

更新:

正确的语法是:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something parameter1: And then describe the variable
   """