document ipython and ipykernel global configuration

docs/source/config/intro.rst

@@ -1,165 +1,233 b''
 =====================================
 Introduction to IPython configuration
 =====================================
 
 .. _setting_config:
 
 Setting configurable options
 ============================
 
 Many of IPython's classes have configurable attributes (see
 :doc:`options/index` for the list). These can be
 configured in several ways.
 
 Python config files
 -------------------
 
 To create the blank config files, run::
 
     ipython profile create [profilename]
 
 If you leave out the profile name, the files will be created for the
-``default`` profile (see :ref:`profiles`). These will typically be
-located in :file:`~/.ipython/profile_default/`, and will be named
-:file:`ipython_config.py`, :file:`ipython_notebook_config.py`, etc.
-The settings in :file:`ipython_config.py` apply to all IPython commands.
+``default`` profile (see :ref:`profiles`). These will typically be located in
+:file:`~/.ipython/profile_default/`, and will be named
+:file:`ipython_config.py`, for hitorical reasons you may also find fiels
+named with IPytho nprefix instead of Jupyter:
+:file:`ipython_notebook_config.py`, etc. The settings in
+:file:`ipython_config.py` apply to all IPython commands.
 
-The files typically start by getting the root config object::
-
-    c = get_config()
+by default, configuration files are fully featured Python scripts that can
+execute arbitrary code, the main usage is to set value on the config object
+``c`` which exist in your configuration file.
 
 You can then configure class attributes like this::
 
     c.InteractiveShell.automagic = False
 
 Be careful with spelling--incorrect names will simply be ignored, with
 no error.
 
-To add to a collection which may have already been defined elsewhere,
-you can use methods like those found on lists, dicts and sets: append,
-extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
-extend, but at the front), add and update (which works both for dicts
-and sets)::
+To add to a collection which may have already been defined elsewhere or have
+default values, you can use methods like those found on lists, dicts and
+sets: append, extend, :meth:`~traitlets.config.LazyConfigValue.prepend` (like
+extend, but at the front), add and update (which works both for dicts and
+sets)::
 
     c.InteractiveShellApp.extensions.append('Cython')
 
 .. versionadded:: 2.0
    list, dict and set methods for config values
 
 Example config file
 ```````````````````
 
 ::
 
     # sample ipython_config.py
-    c = get_config()
 
     c.TerminalIPythonApp.display_banner = True
     c.InteractiveShellApp.log_level = 20
     c.InteractiveShellApp.extensions = [
         'myextension'
     ]
     c.InteractiveShellApp.exec_lines = [
         'import numpy',
         'import scipy'
     ]
     c.InteractiveShellApp.exec_files = [
         'mycode.py',
         'fancy.ipy'
     ]
     c.InteractiveShell.colors = 'LightBG'
     c.InteractiveShell.confirm_exit = False
     c.InteractiveShell.editor = 'nano'
     c.InteractiveShell.xmode = 'Context'
 
     c.PrefilterManager.multi_line_specials = True
 
     c.AliasManager.user_aliases = [
      ('la', 'ls -al')
     ]
 
+Json Configuration files
+------------------------
+
+in case where executability of configuration can be problematic, or
+configurations need to be modified programatically, IPython also support a
+limited set of functionalities via ``.json`` config files. 
+
+You can defined most of the configuration options via a json object which
+hierarchy represent the value you woudl normally set on the ``c`` object of
+``.py`` configuration files. The following ``ipython_config.json`` file::
+
+    {
+        "InteractiveShell": {
+            "colors": "LightBG",
+            "editor": "nano"
+        },
+        "InteractiveShellApp": {
+            "extensions": [
+                "myextension"
+            ]
+        }
+    }
+
+Is equivalent to the following ``ipython_config.py``::
+
+    c.InteractiveShellApp.extensions = [
+        'myextension'
+    ]
+
+    c.InteractiveShell.colors = 'LightBG'
+    c.InteractiveShell.editor = 'nano'
+
 
 Command line arguments
 ----------------------
 
 Every configurable value can be set from the command line, using this
 syntax::
 
     ipython --ClassName.attribute=value
 
 Many frequently used options have short aliases and flags, such as
 ``--matplotlib`` (to integrate with a matplotlib GUI event loop) or
 ``--pdb`` (automatic post-mortem debugging of exceptions).
 
 To see all of these abbreviated options, run::
 
     ipython --help
-    ipython notebook --help
+    jupyter notebook --help
     # etc.
 
 Options specified at the command line, in either format, override
 options set in a configuration file.
 
 The config magic
 ----------------
 
 You can also modify config from inside IPython, using a magic command::
 
     %config IPCompleter.greedy = True
 
 At present, this only affects the current session - changes you make to
 config are not saved anywhere. Also, some options are only read when
 IPython starts, so they can't be changed like this.
 
 .. _configure_start_ipython:
 
 Running IPython from Python
 ----------------------------
 
 If you are using :ref:`embedding` to start IPython from a normal 
 python file, you can set configuration options the same way as in a 
 config file by creating a traitlets config object and passing it to 
 start_ipython like in the example below.
 
 .. literalinclude:: ../../../examples/Embedding/start_ipython_config.py
     :language: python
 
 .. _profiles:
 
 Profiles
 ========
 
 IPython can use multiple profiles, with separate configuration and
 history. By default, if you don't specify a profile, IPython always runs
 in the ``default`` profile. To use a new profile::
 
     ipython profile create foo   # create the profile foo
     ipython --profile=foo        # start IPython using the new profile
 
 Profiles are typically stored in :ref:`ipythondir`, but you can also keep
 a profile in the current working directory, for example to distribute it
 with a project. To find a profile directory on the filesystem::
 
     ipython locate profile foo
 
 .. _ipythondir:
 
 The IPython directory
 =====================
 
 IPython stores its files---config, command history and extensions---in
 the directory :file:`~/.ipython/` by default.
 
 .. envvar:: IPYTHONDIR
 
    If set, this environment variable should be the path to a directory,
    which IPython will use for user data. IPython will create it if it
    does not exist.
 
 .. option:: --ipython-dir=<path>
 
    This command line option can also be used to override the default
    IPython directory.
 
 To see where IPython is looking for the IPython directory, use the command
 ``ipython locate``, or the Python function :func:`IPython.paths.get_ipython_dir`.
+
+
+Systemwide configuration
+========================
+
+It can be usefull to deploy systemwide ipython or ipykernel configuration
+when managing environment for many users. At startup time IPython and
+IPykernel will search for configuration file in multiple systemwide
+locations, mainly:
+
+  - ``/etc/ipython/``
+  - ``/usr/local/etc/ipython/``
+
+When the global install is a standalone python distribution it may also
+search in distribution specific location, for example:
+
+  - ``$ANACONDA_LOCATION/etc/ipython/``
+
+In those locations, Terminal IPython will look for a file called
+``ipython_config.py`` and ``ipython_config.json``, ipykernel will look for
+``ipython_kernel_config.py`` and ``ipython_kernel.json``.
+
+Configuration files are loaded in order and merged with configuration on
+later locatoin taking precedence on earlier locations (that is to say a user
+can overwrite a systemwide configuration option).
+
+You can see all locations in which IPython is looking for configuration files
+by starting ipython in debug mode::
+
+    $ ipython --debug -c 'exit()'
+
+Identically with ipykernel though the command is currently blocking until
+this process is killed with ``Ctrl-\``::
+ 
+    $ python -m ipykernel --debug
  No newline at end of file