From 3ccdbbe5854ff557aedadda99148c756f3866b27 2014-10-07 22:35:12
From: Thomas Kluyver <takowl@gmail.com>
Date: 2014-10-07 22:35:12
Subject: [PATCH] Add Sphinx extension to document line & cell magics

---

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 877a411..8de7e35 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -52,6 +52,7 @@ extensions = [
     'IPython.sphinxext.ipython_directive',
     'numpydoc',  # to preprocess docstrings
     'github',  # for easy GitHub links
+    'magics',
 ]
 
 if ON_RTD:
diff --git a/docs/sphinxext/magics.py b/docs/sphinxext/magics.py
new file mode 100644
index 0000000..401ca0c
--- /dev/null
+++ b/docs/sphinxext/magics.py
@@ -0,0 +1,24 @@
+import re
+from sphinx import addnodes
+
+line_magic_re = re.compile(r"%([\w_]+)")
+cell_magic_re = re.compile(r"%%([\w_]+)")
+
+def parse_magic(env, sig, signode):
+    m = line_magic_re.match(sig)
+    if not m:
+        raise Exception("Invalid magic command: %s" % sig)
+    signode += addnodes.desc_name(sig, sig)
+    return m.group(1)
+
+def parse_cell_magic(env, sig, signode):
+    m = cell_magic_re.match(sig)
+    if not m:
+        raise ValueError("Invalid cell magic: %s" % sig)
+    signode += addnodes.desc_name(sig, sig)
+    return m.group(1)
+
+
+def setup(app):    
+    app.add_object_type('magic', 'magic', '%%%s (magic command)', parse_magic)
+    app.add_object_type('cellmagic', 'cellmagic', '%%%%%s (cell magic)', parse_cell_magic)