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