Merge branch 'doc-config-options' into docs-refresh

Conflicts:
	docs/source/config/index.rst

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

docs/source/config/options/index.rst

@@ -0,0 +1,10
+===============
+IPython options
+===============
+
+.. toctree::
+
+   terminal
+   kernel
+   notebook
+   qtconsole

.gitignore

@@ -1,16 +1,17
 MANIFEST
 build
 dist
 _build
 docs/man/*.gz
 docs/source/api/generated
+docs/source/config/options
 docs/gh-pages
 IPython/html/notebook/static/mathjax
 *.py[co]
 __pycache__
 build
 *.egg-info
 *~
 *.bak
 .ipynb_checkpoints
 .tox

docs/Makefile

@@ -1,144 +1,151
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 SRCDIR        = source
 BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
 
 default: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html        standalone HTML files"
 	@echo "  html_noapi  same as above, without the time consuming API docs"
 	@echo "  pickle      pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp    HTML files and a HTML help project"
 	@echo "  latex       LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  texinfo     Texinfo files"
 	@echo "  info        Texinfo files and run them through makeinfo"
 	@echo "  changes     an overview over all changed/added/deprecated items"
 	@echo "  linkcheck   check all external links for integrity (takes a long time)"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
 	@echo "gitwash-update update git workflow from source repo"
 
 clean_api:
 	-rm -rf $(SRCDIR)/api/generated
 
 clean: clean_api
 	-rm -rf build/* dist/*
+	-rm -rf $(SRCDIR)/config/options/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
 
 all: html pdf
 
 # For final distribution, only build HTML (our pdf is now so large as to be
 # unusable, takes forever to build and just bloats the downloads).  We leave
 # them hardlinked at the top-level so users find them easily, though the
 # original build/html dir is left in-place (useful to reload builds while
 # testing).
 dist: html
 	rm -rf 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:
 	python autogen_api.py
 	@echo "Build API docs finished."
 
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files or run"
 	@echo "  sphinx-web build/pickle"
 	@echo "to start the sphinx-web server."
 
 web: pickle
 
 htmlhelp:
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
 qthelp:
 	mkdir -p build/qthelp
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
 	@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
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
 	mkdir -p build/changes build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
 
 linkcheck:
 	mkdir -p build/linkcheck build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.rst."
 
 gitwash-update:
 	python ../tools/gitwash_dumper.py source/development ipython
 
 nightly: dist
 	rsync -avH --delete dist/ ipython:www/doc/nightly
 
 gh-pages: clean html
 	python gh-pages.py
 
 texinfo:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 info:
 	mkdir -p $(BUILDDIR)/texinfo
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

docs/source/config/index.rst

@@ -1,14 +1,15
 .. _config_index:
 
 ===============================
 Configuration and customization
 ===============================
 
 .. toctree::
    :maxdepth: 2
 
    intro
+   options/index
    extensions/index
    integrating
    inputtransforms
    details