NumpyDoc：标签是如何解析的？

Question

我正在使用 Spyder IDE（Mac OS 上的 v.2.1.11）并编写一些代码，并在为函数编写 DocString（NumpyDoc 格式）时，无法弄清楚为什么 Spyder Object Inspector 以这种奇怪的方式格式化缩进的行。

对于像下面这样的 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“对象检查器”/帮助面板的屏幕截图），在“MJ Mondry, DI 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 中的一个错误，还是其他一些缩进的预期用途？应该如何使用（或不使用）缩进在 Spyder IDE 中生成各种类型的格式（我假设是 NumpyDoc 格式）？
我在NumpyDoc Documentation Page 上没有看到任何关于缩进和自动列表的讨论。

只是想知道我是否可以在这里利用一些有用的未记录的 DocString 功能。 （另一方面，我注意到我可以使用 DocString 中的“References”部分，我会在某个时候将 Ref 移动到该部分。）

谢谢！

我的版本如下： Spyder v2.1.11, 达尔文上的 Python 2.7.6、Qt 4.8.4、PyQt4 (API v2) 4.9.6， Mac OS 10.10.2

Answer 1

(Spyder dev here) 我已经设法通过像这样重新格式化您的文档字符串来获得（我认为）您想要的东西

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（我们用来渲染文档字符串的库）的限制。

注意：Spyder 2.1.11 已经过时了！！请尝试更新到我们的最新版本，即 2.3.4。