Update config docs

docs/autogen_config.py

@@ -6,8 +6,9 @@ from notebook.notebookapp import NotebookApp
 header = """\
 .. _config:
 
-Config
-======
+
+Config file and command line options
+====================================
 
 The notebook server can be run with a variety of command line arguments.
 A list of available options can be found below in the :ref:`options section 

docs/source/frontend_config.rst

@@ -3,25 +3,32 @@
 Configuring the notebook frontend
 =================================
 
-The ability to configure the UI and the preferences on the notebook frontend is
-still work in progress. This document is a rough explanation on how you can
-persist some configuration options for the notebook JavaScript.
+.. note::
+
+    The ability to configure the notebook frontend UI and preferences is
+    still a work in progress.
+
+This document is a rough explanation on how you can persist some configuration
+options for the notebook JavaScript.
 
 There is no exhaustive list on all the configuration option are most options
 are just passed down to other libraries, which mean that non valid
 configuration can be ignored without any error messages.
 
 
-The frontend configuration system works as follow :
+How front end configuration works
+---------------------------------
+The frontend configuration system works as follows::
 
   - get a handle of a configurable JavaScript object.
-  - access it's configuration attribute.
-  - update it's configuration attribute with a JSON patch.
+  - access its configuration attribute.
+  - update its configuration attribute with a JSON patch.
 
-Here is a example on how it's look like for changing the default ``indentUnit``
-for CodeMirror Code Cells:
 
-.. sourcecode::
+Example - Changing the notebook's default indentation
+-----------------------------------------------------
+This example explains how to change the default setting ``indentUnit``
+for CodeMirror Code Cells::
 
     var cell = Jupyter.notebook.get_selected_cell();
     var config = cell.config;
@@ -29,26 +36,26 @@ for CodeMirror Code Cells:
           CodeCell:{
             cm_config:{indentUnit:2}
           }
-        } 
+        }
     config.update(patch)
 
+You can enter the previous snippet in your browser's JavaScript console once.
+Then reload the notebook page in your browser. Now, the preferred indent unit
+should be equal to two spaces. The custom setting persists and you do not need
+to reissue the patch on new notebooks.
 
-
-You can enter the previous snippet in your browser console once, reload the
-notebook page.  Now the default indent unit of all code cell should be equal to
-2 space.  You do not need to reissue the command on new notebooks.
+``indentUnit``, used in this example, is one of the many `Codemirror option
+<https://codemirror.net/doc/manual.html#option_indentUnit>`_ which are available
+for configuration.
 
 
+Example - Restoring the notebook's default indentation
+------------------------------------------------------
+If you want to restore a notebook frontend preference to its default value,
+you will enter a JSON patch with a ``null`` value for the preference setting.
 
-``indentUnit`` is here a `Codemirror option
-<https://codemirror.net/doc/manual.html#option_indentUnit>`_ taken as an
-example, but many other configuration options are available.
-
-If you need to restore the default value just provide a JSON patch with
-``null`` value. For example to restore the indent value to it's default (of 4)
-write the following on your JavaScript console:
-
-.. sourcecode::
+For example, let's restore the indent setting ``indentUnit`` to its default of
+four spaces. Enter the following code snippet in your JavaScript console::
 
     var cell = Jupyter.notebook.get_selected_cell();
     var config = cell.config;
@@ -59,9 +66,14 @@ write the following on your JavaScript console:
         }
     config.update(patch)
 
-
-Under the hood, it will persist the configuration file in
-``~/.jupyter/nbconfig/<section>.json``, with section taking various value
-depending on the page where the configuration is issued.  ``section`` can take
-various value like ``notebook``, ``tree``, ``editor``. A ``common`` section is
-shared by all pages.
+Reload the notebook in your browser and the default indent should again be two
+spaces.
+
+Persisting conguration settings
+-------------------------------
+Under the hood, Jupyter will persist preferred configuration settings in the
+configuration file in ``~/.jupyter/nbconfig/<section>.json``, with ``<section>``
+taking various value depending on the page where the configuration is issued.
+``<section>`` can take various values like ``notebook``, ``tree``, and
+``editor``. A ``common`` section contains configuration settings shared by all
+pages.

docs/source/index.rst

@@ -13,9 +13,9 @@ The Jupyter notebook
    :caption: Configuration
 
    config
-   frontend_config
    public_server
    security
+   frontend_config
    extending/index
 
 .. toctree::