Generate documentation of line & cell magics

docs/autogen_magics.py

@@ -0,0 +1,45 b''
+from IPython.core.alias import Alias
+from IPython.core.interactiveshell import InteractiveShell
+from IPython.utils.text import dedent, indent
+
+shell = InteractiveShell.instance()
+magic_docs = shell.magics_manager.lsmagic_docs()
+
+def isalias(name):
+    return isinstance(shell.magics_manager.magics['line'], Alias)
+
+line_magics = magic_docs['line']
+cell_magics = magic_docs['cell']
+
+output = [
+"Line magics",
+"===========",
+"",
+]
+
+for name, docstring in sorted(line_magics.items()):
+    if isalias(name):
+        # Aliases are magics, but shouldn't be documented here
+        continue
+    output.extend([".. magic:: %{}".format(name),
+                   "",
+                   indent(dedent(docstring)),
+                   ""])
+
+output.extend([
+"Cell magics"
+"==========="
+"",
+])
+
+for name, docstring in sorted(cell_magics.items()):
+    if docstring == line_magics.get(name, 'QQQP'):
+        # Don't redocument line magics that double as cell magics
+        continue
+    output.extend([".. cellmagic:: %%{}".format(name),
+                   "",
+                   indent(dedent(docstring)),
+                   ""])
+
+with open("source/interactive/magics-generated.txt", "w") as f:
+    f.write("\n".join(output))
  No newline at end of file

docs/source/interactive/magics.rst

@@ -0,0 +1,5 b''
+=======================
+Built-in magic commands
+=======================
+
+.. include:: magics-generated.txt

docs/Makefile

@@ -42,6 +42,7 b' clean: clean_api'
 	-rm -rf build/* dist/*
 	-cd $(SRCDIR)/config/options; cat generated | xargs -r rm -f
 	-rm -rf $(SRCDIR)/config/options/generated
+	-rm -f $(SRCDIR)/interactive/magics-generated.txt
 
 pdf: latex
 	cd build/latex && make all-pdf
@@ -58,8 +59,8 b' dist: html'
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
-html: api autoconfig
-html_noapi: clean_api autoconfig
+html: api autoconfig automagic
+html_noapi: clean_api autoconfig automagic
 
 html html_noapi:
 	mkdir -p build/html build/doctrees
@@ -67,6 +68,12 b' html html_noapi:'
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
+automagic: source/interactive/magics-generated.txt
+
+source/interactive/magics-generated.txt:
+	python autogen_magics.py
+	@echo "Created docs for line & cell magics"
+
 autoconfig: source/config/options/generated
 
 source/config/options/generated:

docs/source/interactive/index.rst

@@ -8,6 +8,7 b' Using IPython for interactive work'
    tutorial
    tips
    reference
+   magics
    shell
    qtconsole
 

docs/sphinxext/magics.py

@@ -20,5 +20,5 b' def parse_cell_magic(env, sig, signode):'
 
 
 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)
+    app.add_object_type('magic', 'magic', 'pair: %s; magic command', parse_magic)
+    app.add_object_type('cellmagic', 'cellmagic', 'pair: %s; cell magic', parse_cell_magic)