NumpyDoc：标签是如何解析的？

Question

我正在使用 Spyder IDE（Mac OS 上的 v.2.1.11）并编写一些代码，并为功能，无法弄清楚为什么 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 "Object Inspector"/帮助面板的屏幕截图），意外的粗体和 indentation/list 数字“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 中的错误，还是缩进的其他预期用途？如何在 Spyder IDE（我假设是 NumpyDoc 格式）中使用（或不使用）缩进来生成各种格式？
我在 NumpyDoc Documentation Page.

上没有看到任何关于缩进和自动列表的讨论

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

谢谢！

我的版本如下：蜘蛛 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。

NumpyDoc：标签是如何解析的？

NumpyDoc: How are tabs parsed?

python

docstring

spyder

numpydoc