From 898370ef2bf7e59b1feeaeb55411173afb8a0f11 Mon Sep 17 00:00:00 2001
From: Carol Willing <carolcode@willingconsulting.com>
Date: Wed, 6 Apr 2016 17:30:56 -0700
Subject: [PATCH] Add a configuration overview

---
 docs/source/config_overview.rst | 80 ++++++++++++++++++++++-----------
 docs/source/index.rst           |  2 +-
 2 files changed, 54 insertions(+), 28 deletions(-)

diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst
index 951119f9d..2d42be8e0 100644
--- a/docs/source/config_overview.rst
+++ b/docs/source/config_overview.rst
@@ -3,46 +3,72 @@
 Configuration Overview
 ======================
 
-While Jupyter Notebook installs with default configuration settings, Jupyter
-Notebook provides a rich array of options that may be configured to suit
-your workflow. Let's explore four areas of configuration:
+Beyond the default configuration settings, you can configure a rich array of
+options to suit your workflow. Here are areas that are commonly configured
+when using Jupyter Notebook:
 
-- Jupyter's Common Configuration system
-- Notebook server
-- Notebook front-end client
-- Notebook extensions
+    - :ref:`Jupyter's common configuration system <configure_common>`
+    - :ref:`Notebook server <configure_nbserver>`
+    - :ref:`Notebook front-end client <configure_nbclient>`
+    - :ref:`Notebook extensions <configure_nbextensions>`
 
+Let's look at highlights of each area.
 
-:ref:`Security in Jupyter notebooks <notebook_security>` is a topic worthy of
-serious consideration. Since security policies will vary from organization to
-organization, we encourage you to consult with your security team on settings
-that would be best for your use cases. Our documentation offers some
-responsible security practices, and we recommend that you become familiar
-with the practices.
+.. _configure_common:
 
 Jupyter's Common Configuration system
 -------------------------------------
-- Configuring a Jupyter application
-- Configuring a language kernel
-- Python configuration files
-- Command line arguments
-- traitlets low-level architecture for configuration
+Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
+common configuration system. The process for creating a configuration file
+and editing settings is similar for all the Jupyter applications.
+
+    - `Configuring a Jupyter application <https://jupyter.readthedocs.org/en/latest/config.html#configuring-jupyter-applications>`_
+    - `Using Python to set up the configuration files <https://jupyter.readthedocs.org/en/latest/config.html#python-config-files>`_
+    - `Configuring a language kernel <http://jupyter.readthedocs.org/en/latest/install.html#installing-kernels>`_
+    - `traitlets <https://traitlets.readthedocs.org/en/latest/config.html#module-traitlets.config>`_ provide a low-level
+      architecture for configuration.
+
+.. _configure_nbserver:
 
 Notebook server
 ---------------
+The Notebook server runs the language kernel and communicates with the
+front-end Notebook client (i.e. the familiar notebook interface).
 
-- Configure the Notebook server
-- Running a Notebook server
-- Related: Configuring a language kernel
+	- Configuring the Notebook server
+
+		  To create a ``jupyter_notebook_config.py`` file in the ``.jupyter``
+		  directory, with all the defaults commented out, use the following
+		  command::
+
+	          $ jupyter notebook --generate-config
+
+	      :ref:`Command line arguments for configuation <config>` settings are
+	      documented in the configuration file and the user documentation.
+
+	- :ref:`Running a Notebook server <working_remotely>`
+	- Related: `Configuring a language kernel <http://jupyter.readthedocs.org/en/latest/install.html#installing-kernels>`_
+	  to run in the Notebook server enables your server to run other languages, like R or Julia.
+
+.. _configure_nbclient:
 
 Notebook front-end client
 -------------------------
-- How front-end configuration works
-    * Example: Changing the notebook's default indentation setting
-    * Example: Restoring the notebook's default indentation setting
-- Persisting configuration settings
+- :ref:`How front-end configuration works <frontend_config>`
+    * :ref:`Example: Changing the notebook's default indentation setting <frontend_config>`
+    * :ref:`Example: Restoring the notebook's default indentation setting <frontend_config>`
+- :ref:`Persisting configuration settings <frontend_config>`
+
+.. _configure_nbextensions:
 
 Notebook extensions
 -------------------
-- Distributing Jupyter Extensions as Python Packages
-- Extending the Notebook
+- `Distributing Jupyter Extensions as Python Packages <https://jupyter-notebook.readthedocs.org/en/latest/examples/Notebook/Distributing%20Jupyter%20Extensions%20as%20Python%20Packages.html#Distributing-Jupyter-Extensions-as-Python-Packages>`_
+- `Extending the Notebook <https://jupyter-notebook.readthedocs.org/en/latest/extending/index.html>`_
+
+
+:ref:`Security in Jupyter notebooks:  <notebook_security>` Since security
+policies vary from organization to organization, we encourage you to
+consult with your security team on settings that would be best for your use
+cases. Our documentation offers some responsible security practices, and we
+recommend becoming familiar with the practices.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 376e02e19..33c44d2ce 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -39,7 +39,7 @@ The Jupyter notebook
    frontend_config
    examples/Notebook/Distributing Jupyter Extensions as Python Packages
    extending/index.rst
-   
+
 .. toctree::
    :maxdepth: 1
    :caption: Contributor Documentation