Merge pull request #7871 from takluyver/docs-misc-cleanup-feb15

Misc docs cleanup

IPython/html/services/contents/filemanager.py

@@ -87,13 +87,13 b' class FileContentsManager(FileManagerMixin, ContentsManager):'
         This can be used to process the file on disk,
         such as converting the notebook to a script or HTML via nbconvert.
 
-        It will be called as (all arguments passed by keyword):
+        It will be called as (all arguments passed by keyword)::
 
             hook(os_path=os_path, model=model, contents_manager=instance)
 
-        path: the filesystem path to the file just written
-        model: the model representing the file
-        contents_manager: this ContentsManager instance
+        - path: the filesystem path to the file just written
+        - model: the model representing the file
+        - contents_manager: this ContentsManager instance
         """
     )
     def _post_save_hook_changed(self, name, old, new):

IPython/html/services/contents/manager.py

@@ -81,14 +81,14 b' class ContentsManager(LoggingConfigurable):'
         such as removing notebook outputs or other side effects that
         should not be saved.
 
-        It will be called as (all arguments passed by keyword):
+        It will be called as (all arguments passed by keyword)::
 
             hook(path=path, model=model, contents_manager=self)
 
-        model: the model to be saved. Includes file contents.
-               modifying this dict will affect the file that is stored.
-        path: the API path of the save destination
-        contents_manager: this ContentsManager instance
+        - model: the model to be saved. Includes file contents.
+          Modifying this dict will affect the file that is stored.
+        - path: the API path of the save destination
+        - contents_manager: this ContentsManager instance
         """
     )
     def _pre_save_hook_changed(self, name, old, new):

IPython/html/widgets/interaction.py

@@ -171,7 +171,7 b' def interactive(__interact_f, **kwargs):'
     Parameters
     ----------
     __interact_f : function
-        The function to which the interactive widgets are tied. The **kwargs
+        The function to which the interactive widgets are tied. The `**kwargs`
         should match the function signature.
     **kwargs : various, optional
         An interactive widget is created for each keyword argument that is a
@@ -246,7 +246,7 b' def interact(__interact_f=None, **kwargs):'
     """
     Displays interactive widgets which are tied to a function.
     Expects the first argument to be a function. Parameters to this function are
-    widget abbreviations passed in as keyword arguments (**kwargs). Can be used
+    widget abbreviations passed in as keyword arguments (`**kwargs`). Can be used
     as a decorator (see examples).
 
     Returns
@@ -256,7 +256,7 b' def interact(__interact_f=None, **kwargs):'
     Parameters
     ----------
     __interact_f : function
-        The function to which the interactive widgets are tied. The **kwargs
+        The function to which the interactive widgets are tied. The `**kwargs`
         should match the function signature. Passed to :func:`interactive()`
     **kwargs : various, optional
         An interactive widget is created for each keyword argument that is a
@@ -264,37 +264,37 b' def interact(__interact_f=None, **kwargs):'
 
     Examples
     --------
-    Renders an interactive text field that shows the greeting with the passed in
-    text.
+    Render an interactive text field that shows the greeting with the passed in
+    text::
 
-    1. Invocation of interact as a function
+       # 1. Using interact as a function
        def greeting(text="World"):
            print "Hello {}".format(text)
        interact(greeting, text="IPython Widgets")
         
-    2. Invocation of interact as a decorator
+       # 2. Using interact as a decorator
        @interact
        def greeting(text="World"):
            print "Hello {}".format(text)
         
-    3. Invocation of interact as a decorator with named parameters
+       # 3. Using interact as a decorator with named parameters
        @interact(text="IPython Widgets")
        def greeting(text="World"):
            print "Hello {}".format(text)
         
-    Renders an interactive slider widget and prints square of number.
+    Render an interactive slider widget and prints square of number::
 
-    1. Invocation of interact as a function
+       # 1. Using interact as a function
        def square(num=1):
            print "{} squared is {}".format(num, num*num)
        interact(square, num=5)
 
-    2. Invocation of interact as a decorator
+       # 2. Using interact as a decorator
        @interact
        def square(num=2):
            print "{} squared is {}".format(num, num*num)
         
-    3. Invocation of interact as a decorator with named parameters
+       # 3. Using interact as a decorator with named parameters
        @interact(num=5)
        def square(num=2):
            print "{} squared is {}".format(num, num*num)

docs/autogen_config.py

@@ -1,6 +1,6 b''
 #!/usr/bin/env python
 
-from IPython.utils.text import indent, wrap_paragraphs
+from IPython.utils.text import indent, dedent
 
 from IPython.terminal.ipapp import TerminalIPythonApp
 from IPython.kernel.zmq.kernelapp import IPKernelApp
@@ -34,13 +34,12 b' def document_config_options(classes):'
                     dvr = dvr[:61]+'...'
                 # Double up backslashes, so they get to the rendered docs
                 dvr = dvr.replace('\\n', '\\\\n')
-                lines.append('    Default: ' + dvr)
+                lines.append('    Default: `%s`' % 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))
+                lines.append(indent(dedent(help), 4))
             else:
                 lines.append('    No description')
 
@@ -72,8 +71,7 b" if __name__ == '__main__':"
     write_doc('kernel', 'IPython kernel options', kernel_classes,
         preamble="These options can be used in :file:`ipython_kernel_config.py`",
     )
-    nbclasses = set(NotebookApp().classes) - set(kernel_classes)
-    write_doc('notebook', 'IPython notebook options', nbclasses,
+    write_doc('notebook', 'IPython notebook options', NotebookApp().classes,
         preamble="To configure the IPython kernel, see :doc:`kernel`."
     )
 
@@ -83,8 +81,7 b" if __name__ == '__main__':"
         print("WARNING: Could not import qtconsoleapp. Config options for the "
               "Qt Console will not be documented.")
     else:
-        qtclasses = set(IPythonQtConsoleApp().classes) - set(kernel_classes)
-        write_doc('qtconsole', 'IPython Qt console options', qtclasses,
+        write_doc('qtconsole', 'IPython Qt console options', IPythonQtConsoleApp().classes,
         preamble="To configure the IPython kernel, see :doc:`kernel`."
     )