NumpyDoc:标签是如何解析的？

Question

我正在使用Spyder (在Mac上使用2.1.11版本)并编写一些代码，在为函数编写DocString (NumpyDoc格式)时，我无法理解为什么Spyder对象检查器以这种奇怪的方式格式化缩进行。

对于下面这样的Docstring，在"Calc'd by sellmeier.“后面引用的是缩进的，这导致了奇怪的行为：

def AlInGaAs(x, wl):
'''
Returns the refractive index of ~Al(x)Ga(1-x)In(1-x-y)As (lattice-matched to InP) at the specified wavelength, wl (in microns) and Aluminum content (x=0.0-1.0).  

For lattice-matching, the actual mole ratio, x, is defined as so:
InP-matched X: (Al48 In52 As)_X --> (Ga47 In53 As)_1-X

Valid for wavelengths: 0.900 - 2.100 um  &  x: 0.3 - 1.0

Calc'd by sellmeier equation, with params from
    M. J. Mondry, D. I. Babic, J. E. Bowers, and L. A. Coldren, "Refractive indexes of (Al,Ga,In)As epilayers on InP for optoelectronic applications," Phot. Tech. Lett., vol. 4, no. 6, pp. 627-630, 1992

Parameters
----------
x: float
    Mole ratio of Al, as in: Al(x) Ga(1-x) In(1-x-y) As.  Also varies In slightly for lattice-matching.

wl: float
    wavelength in microns.

...

'''

上面的DocString生成以下输出( Spyder“对象检查器”/help面板的屏幕截图)，在“M.J. Mondry，D.I.Babic.”上有意想不到的粗体化&缩进/列表编号。案文：

​

​

移除缩进时，如下所示：

def AlInGaAs(x, wl):
'''
Returns the refractive index of ~Al(x)Ga(1-x)In(1-x-y)As (lattice-matched to InP) at the specified wavelength, wl (in microns) and Aluminum content (x=0.0-1.0).  

For lattice-matching, the actual mole ratio, x, is defined as so:
InP-matched X: (Al48 In52 As)_X --> (Ga47 In53 As)_1-X

Valid for wavelengths: 0.900 - 2.100 um  &  x: 0.3 - 1.0

Calc'd by sellmeier equation, with params from
*** INDENT REMOVED BELOW ***
M. J. Mondry, D. I. Babic, J. E. Bowers, and L. A. Coldren, "Refractive indexes of (Al,Ga,In)As epilayers on InP for optoelectronic applications," Phot. Tech. Lett., vol. 4, no. 6, pp. 627-630, 1992

Parameters
----------
x: float
    Mole ratio of Al, as in: Al(x) Ga(1-x) In(1-x-y) As.  Also varies In slightly for lattice-matching.

wl: float
    wavelength in microns.

...

'''

看起来很正常，就像这样：

​

​

这只是Spyder中的一个bug，还是其他缩进的用途？如何使用(或不使用)缩进在Spyder (我认为是NumpyDoc格式)中生成各种类型的格式？

我没有看到任何关于NumpyDoc文档页上的缩进和自动列表的讨论。

只是想知道是否有一些有用的、无文档的DocString功能，我可以在这里加以利用。(另外一点，我确实注意到我可以使用DocString中的“Reference”部分，我将在某个时候将Ref移到其中。)

谢谢!

我的版本如下:Spyderv2.1.11，Python2.7.6，Qt 4.8.4，PyQt4 (API v2) 4.9.6在达尔文，MacOS10.10.2

Answer 1

(这里的Spyder)我通过像这样重新格式化您的docstring，得到了(我想)您想要的东西。

def AlInGaAs(x, wl):
'''
Returns the refractive index of ~Al(x)Ga(1-x)In(1-x-y)As (lattice-matched
to InP) at the specified wavelength, wl (in microns) and Aluminum content
(x=0.0-1.0).  

For lattice-matching, the actual mole ratio, x, is defined as so:
InP-matched X: (Al48 In52 As)_X --> (Ga47 In53 As)_1-X

Valid for wavelengths: 0.900 - 2.100 um  &  x: 0.3 - 1.0

Calculated by sellmeier equation, with params from

  M. J. Mondry, D. I. Babic, J. E. Bowers, and L. A. Coldren,
  "Refractive indexes of (Al,Ga,In)As epilayers on InP for optoelectronic
  applications," Phot. Tech. Lett., vol. 4, no. 6, pp. 627-630, 1992

Parameters
----------
x: float
    Mole ratio of Al, as in: Al(x) Ga(1-x) In(1-x-y) As.  Also varies In
    slightly for lattice-matching.

wl: float
    wavelength in microns.

'''

我所做的唯一一件事就是打破了你在79列上的(非常)长队。也许这是Sphinx (我们用来呈现文档字符串的库)的一个限制。

注:间谍2.1.11是古老的！！请尝试更新我们的最新版本，即2.3.4。