Merge pull request #4492 from takluyver/docs-refresh

Configuration docs refresh

- Moved the technical details of the config system into the development directory.
- Added a new 'intro' document describing how to use the config system, without the technical info.
- Autogenerate lists of config options for the main components (this doesn't yet include the parallel machinery).
- Condense and tidy up other config docs, removing outdated information.

.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]

IPython/core/shellapp.py

@@ -195,7 +195,7 @@ def _extra_extension_changed(self, name, old, new):
     )
     pylab_import_all = Bool(True, config=True,
         help="""If true, IPython will populate the user namespace with numpy, pylab, etc.
-        and an 'import *' is done from numpy and pylab, when using pylab mode.
+        and an ``import *`` is done from numpy and pylab, when using pylab mode.
         
         When False, pylab mode should not import any names into the user namespace.
         """

IPython/qt/console/console_widget.py

@@ -130,15 +130,18 @@ class ConsoleWidget(MetaQObjectHasTraits('NewBase', (LoggingConfigurable, QtGui.
         help="""
         The type of paging to use. Valid values are:
 
-            'inside' : The widget pages like a traditional terminal.
-            'hsplit' : When paging is requested, the widget is split
-                       horizontally. The top pane contains the console, and the
-                       bottom pane contains the paged text.
-            'vsplit' : Similar to 'hsplit', except that a vertical splitter
-                       used.
-            'custom' : No action is taken by the widget beyond emitting a
-                       'custom_page_requested(str)' signal.
-            'none'   : The text is written directly to the console.
+        'inside'
+           The widget pages like a traditional terminal.
+        'hsplit'
+           When paging is requested, the widget is split horizontally. The top
+           pane contains the console, and the bottom pane contains the paged text.
+        'vsplit'
+           Similar to 'hsplit', except that a vertical splitter is used.
+        'custom'
+           No action is taken by the widget beyond emitting a
+           'custom_page_requested(str)' signal.
+        'none'
+           The text is written directly to the console.
         """)
 
     font_family = Unicode(config=True,

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,15 +57,21 @@ 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
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@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

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\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

docs/source/_static/default.css

@@ -120,6 +120,11 @@ dd {
     color: #060;
 }
 
+dt {
+    font-weight: bold;
+    padding-left: 0.5em;
+}
+
 dt:target,
 .highlight {
     background-color: #fbe54e;
@@ -480,6 +485,12 @@ span.linkdescr {
     font-size: 90%;
 }
 
+.search input[name=q] {
+    max-width: 100%;
+    box-sizing: border-box;
+    -moz-box-sizing: border-box;
+}
+
 ul.search {
     margin: 10px 0 0 20px;
     padding: 0;