documentation build broken in bb429da5b

[bfroehle]

commit bb429da (#2124) broke the documentation build
see https://launchpadlibrarian.net/111097427/buildlog_ubuntu-quantal-i386.ipython_0.13%2B2735-0~26~quantal1_FAILEDTOBUILD.txt.gz for a failure on ubuntu 12.10, same failure on 12.04 ans 11.10

  File "/usr/lib/python2.7/dist-packages/sphinx/util/docstrings.py", line 24, in prepare_docstring
    lines = s.expandtabs().splitlines()
AttributeError: 'property' object has no attribute 'expandtabs'

[takluyver]

It's the use of the properties for instance.__doc__ that's breaking it. When autodoc accesses Class.__doc__, it gets the property instead of the real docstring.

I suggest we set self.__doc__ within __init__, so long as that works.

[bfroehle]

Yes, we can just set self.__doc__ in __init__. The help gets a bit longer:

In [1]: ed?
Type:       Magic function
String Form:<IPython.core.magic.MagicAlias object at 0x1f94250>
Namespace:  IPython internal
File:       /home/bfroehle/src/ipython/IPython/core/magic.py
Definition: ed(self, *args, **kwargs)
Docstring:  Alias for `%edit`.
Call def:   ed(self, *args, **kwargs)
Call docstring:Call the magic alias.

vs.

In [2]: ed?
Type:       Magic function
String Form:<IPython.core.magic.MagicAlias object at 0x29d1bd0>
Namespace:  IPython internal
File:       /home/bfroehle/src/ipython/IPython/core/magic.py
Definition: ed(self, *args, **kwargs)
Docstring:  Alias for `%edit`.
Class Docstring:
Store a magic alias.

An alias is determined by its magic name and magic kind. Lookup
is done at call time, so if the underlying magic changes the alias
will call the new function.

Use the :meth:`MagicsManager.register_alias` method or the
`%alias_magic` magic function to create and register a new alias.
Call def:   ed(self, *args, **kwargs)
Call docstring:Call the magic alias.

However that is just because the __doc__ property was shadowing the regular class help.

[bfroehle]

Manually tested the fix by running:

PYTHONPATH=`pwd` make -C docs html

[bfroehle]

Test results for commit 48897c1 merged into master
Platform: linux2

• python2.6: OK (libraries not available: matplotlib oct2py pymongo qt rpy2 wx wx.aui)
• python2.7: OK
• python3.2: OK (libraries not available: oct2py pymongo rpy2 wx wx.aui)

Not available for testing:

[takluyver]

I've got no complaints if you want to merge this.

[bfroehle]

Well, I came up with an alternative approach which maintains some dynamism... is it too convoluted?

[takluyver]

I vote to keep it simple. I'm not sure what dynamism adds.

[bfroehle]

Great, reverted and pushed! :)