[IPython-dev] Bug in our magic_arguments decorator for building docstrings (ping R. Kern)?

Robert Kern robert.kern at gmail.com
Tue Jun 5 16:57:47 EDT 2012


On 6/5/12 7:57 PM, Fernando Perez wrote:
> Hey folks,
>
> I'm sending this in case anyone already knows what's going on, or is
> willing to dig into this issue a bit.
>
> A while back we added (from R. Kern) the new magic_arguments module:
>
> https://github.com/ipython/ipython/blob/master/IPython/core/magic_arguments.py
>
> that allows you to build magics with a more friendly decorator-based
> syntax.  But it seems that this decorator is severely mangling
> docstrings, consider how the new Rmagic docs look:
>
> http://ipython.org/ipython-doc/dev/config/extensions/rmagic.html
>
> The problem can even be seen with a simple example:
>
> ###
> from IPython.core.magic_arguments import magic_arguments
>
> @magic_arguments()
> def f():
>      """A long
>
>      docstring
>
>      with::
>
>         code
>         blocks
>
>      and more text:
>
>      * one
>      * two
>      * three
>     """
> ####
>
> If we run this, we get:
>
> In [5]: run ~/margs.py
>
> In [6]: f?
> Type:       function
> Base Class:<type 'function'>
> String Form:<function f at 0x2dce410>
> Namespace:  Interactive
> File:       /home/fperez/margs.py
> Definition: f()
> Docstring:
> %f
>
> A long docstring with:: code blocks and more text: * one * two * three
>
> In [7]:
>
> As can be seen above, the entire docstring got rammed into a single line.
>
> Has anyone encountered this before?  Robert, any ideas?

We probably want to use the RawDescriptionHelpFormatter:

   http://docs.python.org/library/argparse#argparse.RawDescriptionHelpFormatter

Or a custom implementation that removes the leading indentation but otherwise 
leaves the line breaks and indents alone.

Sorry for not noticing that earlier. All of my magics had single-line 
descriptions. :-)

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
  that is made terrible by our own mad attempt to interpret it as though it had
  an underlying truth."
   -- Umberto Eco




More information about the IPython-dev mailing list