Repository: ipython/ipython

Issue:
Line magic function `%R` not found. (Rmagic)
The documentation page could quickly remind that "%load_ext rmagic" is required before anything.
http://ipython.org/ipython-doc/dev/config/extensions/rmagic.html

(it is the case on the page for the extension autoreload)



Discussion:
That is precisely on the [previous page](http://ipython.org/ipython-doc/dev/config/extensions/index.html#using-extensions), but I suppose it makes sense to add a mention at every level.

I'd think it would make it easier when the previous page refers to an extension called "Rmagic" that can only be loaded when called "rmagic".

The Rmagic/rmagic thing was issue #2003. It's been fixed, and will appear when the docs are next rebuilt.

closing as fixed by #2003

I'd argue for re-opening this bug. Many will arrive at the rmagic page directly from a google or sphynx search. They won't necessarily have the context of the previous page. It's a tiny amount of text to add it again on the rmagic page.

Seconded. I keep forgetting it, and google always directs me to that page. Not every magic method needs loading.

Third...ed? Right, many people get there via google and will miss the preceding page.

Make it a quartet.

This was closed without the issue addressed (the second minor comment regarding the inconsistent use of Rmagic/rmagic was fixed though). 

Right, re-opened. Who wants to whip up a pull request to fix it? The docs are in `docs/source/`.

Which branch should this target? master?

Also - I just had a look at the code, the actual documentation that's now rendered is largely in the docstring for the relevant module, i.e., in `IPython/extensions/*magic.py`. I'm happy to make this change. But so that "everything (that you're going to edit) is all in one place," I think it makes sense to make the changes in those docstrings. And we may as well change all of the magics while we're at it.

The fix would just be the addition of something like, "To enable, execute `%load_ext *magic`." In an ideal world, I'd provide a pointer to the info in extensions/index.rst, but this seems like a hassle to do cleanly, and things have been going along well enough without any of this.

Does that sound about right?

Yes, I remembered later that the magics docs are in the module docstrings. Changing it there would be best. And yes, a simple message explaining to use `%load_ext rmagic` to enable it will be fine.

Target the PR against master, and mention that it's a candidate for backporting to 1.x.

Thanks!

It turns out that sphinx is somewhat broken by graphviz,which switched to a stricter parser in 2.30. Its reported in the [sphinx issue tracker](https://bitbucket.org/birkenfeld/sphinx/issue/1131/inheritance-diagram-graphviz-issue), but not quite recognized by the sphinx folks as a problem as far as I can see. The solution now is apparently to downgrade to 2.28. Or, perhaps there is a problem with our usage of sphinx. I'm a bit out of my league on tracking that down, though.

I'm not opening this as an ipython issue, but if anyone thinks it should be, feel free. I'll also respond to queries about this issue here.

No, I don't think there's any reason to open that as an IPython issue. Hopefully, it will get worked out soon.


Resolving patch:
diff --git a/IPython/extensions/cythonmagic.py b/IPython/extensions/cythonmagic.py
--- a/IPython/extensions/cythonmagic.py
+++ b/IPython/extensions/cythonmagic.py
@@ -4,9 +4,18 @@
 Cython related magics
 =====================
 
+Magic command interface for interactive work with Cython
+
+.. note::
+
+  The ``Cython`` package needs to be installed separately. It
+  can be obtained using ``easy_install`` or ``pip``.
+
 Usage
 =====
 
+To enable the magics below, execute ``%load_ext cythonmagic``.
+
 ``%%cython``
 
 {CYTHON_DOC}
diff --git a/IPython/extensions/octavemagic.py b/IPython/extensions/octavemagic.py
--- a/IPython/extensions/octavemagic.py
+++ b/IPython/extensions/octavemagic.py
@@ -11,9 +11,13 @@
   The ``oct2py`` module needs to be installed separately and
   can be obtained using ``easy_install`` or ``pip``.
 
+  You will also need a working copy of GNU Octave.
+
 Usage
 =====
 
+To enable the magics below, execute ``%load_ext octavemagic``.
+
 ``%octave``
 
 {OCTAVE_DOC}
diff --git a/IPython/extensions/rmagic.py b/IPython/extensions/rmagic.py
--- a/IPython/extensions/rmagic.py
+++ b/IPython/extensions/rmagic.py
@@ -6,9 +6,18 @@
 
 Magic command interface for interactive work with R via rpy2
 
+.. note::
+
+  The ``rpy2`` package needs to be installed separately. It
+  can be obtained using ``easy_install`` or ``pip``.
+
+  You will also need a working copy of R.
+
 Usage
 =====
 
+To enable the magics below, execute ``%load_ext rmagic``.
+
 ``%R``
 
 {R_DOC}
@@ -425,12 +434,12 @@ def R(self, line, cell=None, local_ns=None):
         is printed if it would printed be when evaluating the same code 
         within a standard R REPL.
         
-        Nothing is returned to python by default in cell mode.
+        Nothing is returned to python by default in cell mode::
 
             In [10]: %%R
                ....: Y = c(2,4,3,9)
                ....: summary(lm(Y~X))
-       
+
             Call:
             lm(formula = Y ~ X)
 
@@ -447,9 +456,9 @@ def R(self, line, cell=None, local_ns=None):
             Multiple R-squared: 0.6993,Adjusted R-squared: 0.549
             F-statistic: 4.651 on 1 and 2 DF,  p-value: 0.1638
 
-        In the notebook, plots are published as the output of the cell.
+        In the notebook, plots are published as the output of the cell::
 
-        %R plot(X, Y)
+            %R plot(X, Y)
 
         will create a scatter plot of X bs Y.
 
@@ -475,19 +484,19 @@ def R(self, line, cell=None, local_ns=None):
         * If the cell is not None, the magic returns None.
 
         * If the cell evaluates as False, the resulting value is returned
-        unless the final line prints something to the console, in
-        which case None is returned.
+          unless the final line prints something to the console, in
+          which case None is returned.
 
         * If the final line results in a NULL value when evaluated
-        by rpy2, then None is returned.
+          by rpy2, then None is returned.
 
         * No attempt is made to convert the final value to a structured array.
-        Use the --dataframe flag or %Rget to push / return a structured array.
+          Use the --dataframe flag or %Rget to push / return a structured array.
 
         * If the -n flag is present, there is no return value.
 
         * A trailing ';' will also result in no return value as the last
-        value in the line is an empty string.
+          value in the line is an empty string.
 
         The --dataframe argument will attempt to return structured arrays. 
         This is useful for dataframes with


Test patch: