Add a configuration overview

docs/source/config_overview.rst

@@ -3,46 +3,72 @@
 Configuration Overview
 ======================
 
-While Jupyter Notebook installs with default configuration settings, Jupyter
+Beyond the default configuration settings, you can configure a rich array of
-Notebook provides a rich array of options that may be configured to suit
+options to suit your workflow. Here are areas that are commonly configured
-your workflow. Let's explore four areas of configuration:
+when using Jupyter Notebook:
 
-- Jupyter's Common Configuration system
+    - :ref:`Jupyter's common configuration system <configure_common>`
-- Notebook server
+    - :ref:`Notebook server <configure_nbserver>`
-- Notebook front-end client
+    - :ref:`Notebook front-end client <configure_nbclient>`
-- Notebook extensions
+    - :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
+.. _configure_common:
-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.
 
 Jupyter's Common Configuration system
 -------------------------------------
-- Configuring a Jupyter application
+Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
-- Configuring a language kernel
+common configuration system. The process for creating a configuration file
-- Python configuration files
+and editing settings is similar for all the Jupyter applications.
-- Command line arguments
+
-- traitlets low-level architecture for configuration
+    - `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
+	- Configuring the Notebook server
-- Running a Notebook server
+
-- Related: Configuring a language kernel
+		  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
+- :ref:`How front-end configuration works <frontend_config>`
-    * Example: Changing the notebook's default indentation setting
+    * :ref:`Example: Changing the notebook's default indentation setting <frontend_config>`
-    * Example: Restoring the notebook's default indentation setting
+    * :ref:`Example: Restoring the notebook's default indentation setting <frontend_config>`
-- Persisting configuration settings
+- :ref:`Persisting configuration settings <frontend_config>`
+
+.. _configure_nbextensions:
 
 Notebook extensions
 -------------------
-- Distributing Jupyter Extensions as Python Packages
+- `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
+- `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.

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