Fix documentation of functions using magic_arguments

IPython/core/magics/basic.py

@@ -114,6 +114,7 b' class BasicMagics(Magics):'
         Examples
         --------
         ::
+
           In [1]: %alias_magic t timeit
           Created `%t` as an alias for `%timeit`.
           Created `%%t` as an alias for `%%timeit`.

IPython/extensions/cythonmagic.py

@@ -68,6 +68,7 b' from IPython.core import magic_arguments'
 from IPython.core.magic import Magics, magics_class, cell_magic
 from IPython.utils import py3compat
 from IPython.utils.path import get_ipython_cache_dir
+from IPython.utils.text import dedent
 
 import Cython
 from Cython.Compiler.Errors import CompileError
@@ -331,9 +332,12 b' class CythonMagics(Magics):'
         return html
 
 __doc__ = __doc__.format(
-                CYTHON_DOC = ' '*8 + CythonMagics.cython.__doc__,
-                CYTHON_INLINE_DOC = ' '*8 + CythonMagics.cython_inline.__doc__,
-                CYTHON_PYXIMPORT_DOC = ' '*8 + CythonMagics.cython_pyximport.__doc__,
+                # rST doesn't see the -+ flag as part of an option list, so we
+                # hide it from the module-level docstring.
+                CYTHON_DOC = dedent(CythonMagics.cython.__doc__\
+                            .replace('-+, --cplus','--cplus    ')),
+                CYTHON_INLINE_DOC = dedent(CythonMagics.cython_inline.__doc__),
+                CYTHON_PYXIMPORT_DOC = dedent(CythonMagics.cython_pyximport.__doc__),
 )
 
 def load_ipython_extension(ip):

IPython/extensions/octavemagic.py

@@ -55,6 +55,7 b' from IPython.core.magic_arguments import ('
     argument, magic_arguments, parse_argstring
 )
 from IPython.utils.py3compat import unicode_to_str
+from IPython.utils.text import dedent
 
 class OctaveMagicError(oct2py.Oct2PyError):
     pass
@@ -145,6 +146,8 b' class OctaveMagics(Magics):'
         '''
         Line-level magic that pulls a variable from Octave.
 
+        ::
+
             In [18]: _ = %octave x = [1 2; 3 4]; y = 'hello'
 
             In [19]: %octave_pull x y
@@ -195,7 +198,7 b' class OctaveMagics(Magics):'
     def octave(self, line, cell=None, local_ns=None):
         '''
         Execute code in Octave, and pull some of the results back into the
-        Python namespace.
+        Python namespace::
 
             In [9]: %octave X = [1 2; 3 4]; mean(X)
             Out[9]: array([[ 2., 3.]])
@@ -209,9 +212,9 b' class OctaveMagics(Magics):'
 
             -2*x^4 - 1*x^3 + 0*x^2 + 1*x^1 + 2
 
-        In the notebook, plots are published as the output of the cell, e.g.
+        In the notebook, plots are published as the output of the cell, e.g.::
 
-        %octave plot([1 2 3], [4 5 6])
+            %octave plot([1 2 3], [4 5 6])
 
         will create a line plot.
 
@@ -360,9 +363,9 b' class OctaveMagics(Magics):'
 
 
 __doc__ = __doc__.format(
-    OCTAVE_DOC = ' '*8 + OctaveMagics.octave.__doc__,
-    OCTAVE_PUSH_DOC = ' '*8 + OctaveMagics.octave_push.__doc__,
-    OCTAVE_PULL_DOC = ' '*8 + OctaveMagics.octave_pull.__doc__
+    OCTAVE_DOC = dedent(OctaveMagics.octave.__doc__),
+    OCTAVE_PUSH_DOC = dedent(OctaveMagics.octave_push.__doc__),
+    OCTAVE_PULL_DOC = dedent(OctaveMagics.octave_pull.__doc__)
     )
 
 

IPython/extensions/rmagic.py

@@ -75,6 +75,7 b' from IPython.core.magic_arguments import ('
 from IPython.external.simplegeneric import generic
 from IPython.utils.py3compat import (str_to_unicode, unicode_to_str, PY3,
                                      unicode_type)
+from IPython.utils.text import dedent
 
 class RInterpreterError(ri.RRuntimeError):
     """An error when running R code in a %%R magic cell."""
@@ -679,10 +680,10 b' class RMagics(Magics):'
                 return self.Rconverter(result, dataframe=False)
 
 __doc__ = __doc__.format(
-                R_DOC = ' '*8 + RMagics.R.__doc__,
-                RPUSH_DOC = ' '*8 + RMagics.Rpush.__doc__,
-                RPULL_DOC = ' '*8 + RMagics.Rpull.__doc__,
-                RGET_DOC = ' '*8 + RMagics.Rget.__doc__
+                R_DOC = dedent(RMagics.R.__doc__),
+                RPUSH_DOC = dedent(RMagics.Rpush.__doc__),
+                RPULL_DOC = dedent(RMagics.Rpull.__doc__),
+                RGET_DOC = dedent(RMagics.Rget.__doc__)
 )
 
 

IPython/parallel/client/magics.py

@@ -46,6 +46,7 b' from IPython.core.error import UsageError'
 from IPython.core.magic import Magics
 from IPython.core import magic_arguments
 from IPython.testing.skipdoctest import skip_doctest
+from IPython.utils.text import dedent
 
 #-----------------------------------------------------------------------------
 # Definitions of magic functions for use with IPython
@@ -108,13 +109,11 b' def output_args(f):'
             
             Choices are:
             
-            type: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
-            
-            engine: display all output for each engine together.
-
-            order: like type, but individual displaypub output from each engine is collated.
-                For example, if multiple plots are generated by each engine, the first
-                figure of each engine will be displayed, then the second of each, etc.
+            **type**: group outputs of all engines by type (stdout, stderr, displaypub, etc.).
+            **engine**: display all output for each engine together.
+            **order**: like type, but individual displaypub output from each engine is collated.
+              For example, if multiple plots are generated by each engine, the first
+              figure of each engine will be displayed, then the second of each, etc.
             """
         ),
         magic_arguments.argument('-o', '--out', dest='save_name', type=str,
@@ -435,8 +434,8 b' class ParallelMagics(Magics):'
 
 
 __doc__ = __doc__.format(
-                AUTOPX_DOC = ' '*8 + ParallelMagics.autopx.__doc__,
-                PX_DOC = ' '*8 + ParallelMagics.px.__doc__,
-                RESULT_DOC = ' '*8 + ParallelMagics.result.__doc__,
-                CONFIG_DOC = ' '*8 + ParallelMagics.pxconfig.__doc__,
+                AUTOPX_DOC = dedent(ParallelMagics.autopx.__doc__),
+                PX_DOC = dedent(ParallelMagics.px.__doc__),
+                RESULT_DOC = dedent(ParallelMagics.result.__doc__),
+                CONFIG_DOC = dedent(ParallelMagics.pxconfig.__doc__),
 )