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,7 +212,7 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])
 
@@ -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,11 +109,9 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.
+            **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.
             """
@@ -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__),
 )