From 36514bb627de7303e35042447acfb4a5d1ffbb78 2013-11-05 18:13:34
From: Thomas Kluyver <takowl@gmail.com>
Date: 2013-11-05 18:13:34
Subject: [PATCH] Merge branch 'doc-config-options' into docs-refresh

Conflicts:
	docs/source/config/index.rst

---

diff --git a/.gitignore b/.gitignore
index 703b7bc..8c1d8b2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,7 @@ dist
 _build
 docs/man/*.gz
 docs/source/api/generated
+docs/source/config/options
 docs/gh-pages
 IPython/html/notebook/static/mathjax
 *.py[co]
diff --git a/docs/Makefile b/docs/Makefile
index 6d20ed1..f835fdf 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -40,6 +40,7 @@ clean_api:
 
 clean: clean_api
 	-rm -rf build/* dist/*
+	-rm -rf $(SRCDIR)/config/options/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
@@ -56,8 +57,8 @@ dist: html
 	cp -al build/html .
 	@echo "Build finished.  Final docs are in html/"
 
-html: api 
-html_noapi: clean_api
+html: api autoconfig
+html_noapi: clean_api autoconfig
 
 html html_noapi:
 	mkdir -p build/html build/doctrees
@@ -65,6 +66,12 @@ html html_noapi:
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
+autoconfig: source/config/options/generated
+
+source/config/options/generated:
+	python autogen_config.py
+	@echo "Created docs for config options"
+
 api: source/api/generated/gen.txt
 
 source/api/generated/gen.txt:
@@ -98,7 +105,7 @@ qthelp:
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
 
-latex: api
+latex: api autoconfig
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
diff --git a/docs/autogen_config.py b/docs/autogen_config.py
new file mode 100644
index 0000000..cf62376
--- /dev/null
+++ b/docs/autogen_config.py
@@ -0,0 +1,74 @@
+from IPython.utils.text import indent, wrap_paragraphs
+
+from IPython.terminal.ipapp import TerminalIPythonApp
+from IPython.kernel.zmq.kernelapp import IPKernelApp
+from IPython.html.notebookapp import NotebookApp
+from IPython.qt.console.qtconsoleapp import IPythonQtConsoleApp
+
+def document_config_options(classes):
+    lines = []
+    for cls in classes:
+        classname = cls.__name__
+        for k, trait in sorted(cls.class_traits(config=True).items()):
+            ttype = trait.__class__.__name__
+
+            termline = classname + '.' + trait.name
+
+            # Choices or type
+            if 'Enum' in ttype:
+                # include Enum choices
+                termline += ' : ' + '|'.join(repr(x) for x in trait.values)
+            else:
+                termline += ' : ' + ttype
+            lines.append(termline)
+
+            # Default value
+            try:
+                dv = trait.get_default_value()
+                dvr = repr(dv)
+            except Exception:
+                dvr = dv = None # ignore defaults we can't construct
+            if (dv is not None) and (dvr is not None):
+                if len(dvr) > 64:
+                    dvr = dvr[:61]+'...'
+                # Double up backslashes, so they get to the rendered docs
+                dvr = dvr.replace('\\n', '\\\\n')
+                lines.append('    Default: ' + dvr)
+                lines.append('')
+
+            help = trait.get_metadata('help')
+            if help is not None:
+                help = '\n'.join(wrap_paragraphs(help, 76))
+                lines.append(indent(help, 4))
+            else:
+                lines.append('    No description')
+
+            lines.append('')
+    return '\n'.join(lines)
+
+kernel_classes = IPKernelApp().classes
+
+def write_doc(filename, title, classes, preamble=None):
+    configdoc = document_config_options(classes)
+    with open('source/config/options/%s.rst' % filename, 'w') as f:
+        f.write(title + '\n')
+        f.write(('=' * len(title)) + '\n')
+        f.write('\n')
+        if preamble is not None:
+            f.write(preamble + '\n\n')
+        f.write(configdoc)
+
+if __name__ == '__main__':
+    write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp().classes)
+    write_doc('kernel', 'IPython kernel options', kernel_classes,
+              preamble="These options can be used in :file:`ipython_notebook_config.py` "
+              "or in :file:`ipython_qtconsole_config.py`")
+    nbclasses = set(NotebookApp().classes) - set(kernel_classes)
+    write_doc('notebook', 'IPython notebook options', nbclasses,
+              preamble="Any of the :doc:`kernel` can also be used.")
+    qtclasses = set(IPythonQtConsoleApp().classes) - set(kernel_classes)
+    write_doc('qtconsole', 'IPython Qt console options', qtclasses,
+              preamble="Any of the :doc:`kernel` can also be used.")
+
+    with open('source/config/options/generated', 'w'):
+        pass
\ No newline at end of file
diff --git a/docs/source/config/index.rst b/docs/source/config/index.rst
index 6e3d182..3db51ee 100644
--- a/docs/source/config/index.rst
+++ b/docs/source/config/index.rst
@@ -8,6 +8,7 @@ Configuration and customization
    :maxdepth: 2
 
    intro
+   options/index
    extensions/index
    integrating
    inputtransforms
diff --git a/docs/source/config/options/index.rst b/docs/source/config/options/index.rst
new file mode 100644
index 0000000..ef5d9af
--- /dev/null
+++ b/docs/source/config/options/index.rst
@@ -0,0 +1,10 @@
+===============
+IPython options
+===============
+
+.. toctree::
+
+   terminal
+   kernel
+   notebook
+   qtconsole