NumpyDoc: How are tabs parsed?

Question

I'm using the Spyder IDE (v.2.1.11 on Mac OS) and writing some code, and in writing a DocString (NumpyDoc format) for a function, can't figure out why the Spyder Object Inspector formats an indented line in this strange way.

For a Docstring like the one below, the paper reference after "Calc'd by sellmeier..." is indented, which causes the strange behaviour:

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.

...

'''

The above DocString produces the following output (screenshot of the Spyder "Object Inspector"/help panel), with the unexpected bolding & indentation/list numbers on the "M. J. Mondry, D. I. Babic..." text:

Strange indentation and listing of the Paper Reference.

While removing the indent, as so:

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.

...

'''

Looks normal, as so:

Object Inspector with un-Indented paper reference

Is that just a bug in Spyder, or some other intended use of indenting? How is one supposed to use (or not use) indents to produce various types of formatting in the Spyder IDE (which I assume is NumpyDoc format)?
I don't see any discussion of indentation and automatic lists on the NumpyDoc Documentation Page.

Just wondering if there's some useful undocumented DocString functionality I could be taking advantage of here. (On another note, I do notice that I could use the "References" section in the DocString, which I will move the Ref into at some point.)

Thanks!

My versions are as follows: Spyder v2.1.11, Python 2.7.6, Qt 4.8.4, PyQt4 (API v2) 4.9.6 on Darwin, Mac OS 10.10.2

score 0 · Accepted Answer · answered Apr 14 '15 at 19:54

(Spyder dev here) I've managed to get what (I think) you want by reformatting your docstring like this

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.

'''

The only thing I did was to broke your (very) long lines at 79 columns. Maybe that's a limitation of Sphinx (the library we use to render docstrings).

Note: Spyder 2.1.11 is ancient old!! Please try to update to our latest version, which is 2.3.4.

Thanks! I agree that it's a bit unfortunate that I'd have to manually line-break all my documentation - I was just expecting Spyder to wrap the text appropriately. Do you know why the `13.` & `10.` numbered listing was added? I have upgraded my Spyder - I'll see if it still behaves that way. — Demis, May 04 '15 at 17:52
I really don't know. I think it's a problem with Sphinx because we don't do anything other than passing docstrings to Sphinx for it to render them :-) — Carlos Cordoba, May 04 '15 at 18:42

NumpyDoc: How are tabs parsed?

1 Answers1