From 916e70316a6124cbfb7293e9e31e42424d4d405e 2015-05-28 19:01:04
From: Thomas Kluyver <takowl@gmail.com>
Date: 2015-05-28 19:01:04
Subject: [PATCH] Use new traitlets API to generate config docs

Relies on ipython/traitlets#21

---

diff --git a/docs/autogen_config.py b/docs/autogen_config.py
index fe9cb56..4ec4701 100755
--- a/docs/autogen_config.py
+++ b/docs/autogen_config.py
@@ -1,54 +1,9 @@
 #!/usr/bin/env python
 
-from IPython.utils.text import indent, dedent
-
 from IPython.terminal.ipapp import TerminalIPythonApp
-from IPython.kernel.zmq.kernelapp import IPKernelApp
-
-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: `%s`' % dvr)
-                lines.append('')
-
-            help = trait.get_metadata('help')
-            if help is not None:
-                lines.append(indent(dedent(help), 4))
-            else:
-                lines.append('    No description')
-
-            lines.append('')
-    return '\n'.join(lines)
-
-kernel_classes = IPKernelApp().classes
+from ipykernel.kernelapp import IPKernelApp
 
-def write_doc(name, title, classes, preamble=None):
-    configdoc = document_config_options(classes)
+def write_doc(name, title, app, preamble=None):
     filename = '%s.rst' % name
     with open('source/config/options/%s' % filename, 'w') as f:
         f.write(title + '\n')
@@ -56,7 +11,7 @@ def write_doc(name, title, classes, preamble=None):
         f.write('\n')
         if preamble is not None:
             f.write(preamble + '\n\n')
-        f.write(configdoc)
+        f.write(app.document_config_options())
     with open('source/config/options/generated', 'a') as f:
         f.write(filename + '\n')
 
@@ -66,8 +21,9 @@ if __name__ == '__main__':
     with open('source/config/options/generated', 'w'):
         pass
 
-    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_kernel_config.py`",
+    write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp())
+    write_doc('kernel', 'IPython kernel options', IPKernelApp(),
+        preamble=("These options can be used in :file:`ipython_kernel_config.py`. "
+                  "The kernel also respects any options in `ipython_config.py`"),
     )