First pass at editing pr

docs/requirements.txt

@@ -1,3 +1,3
--e .
+-e ../.
 ipykernel
 setuptools>=18.5

docs/source/conf.py

@@ -1,282 +1,284
 # -*- coding: utf-8 -*-
 #
 # IPython documentation build configuration file.
 
 # NOTE: This file has been edited manually from the auto-generated one from
 # sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
 # needed, generate a scratch one and merge by hand any new fields needed.
 
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
 import sys, os
 
 ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
 
 if ON_RTD:
     # Mock the presence of matplotlib, which we don't have on RTD
     # see
     # http://read-the-docs.readthedocs.io/en/latest/faq.html
     tags.add('rtd')
 
     # RTD doesn't use the Makefile, so re-run autogen_{things}.py here.
     for name in ('config', 'api', 'magics'):
         fname = 'autogen_{}.py'.format(name)
         fpath = os.path.abspath(os.path.join('..', fname))
         with open(fpath) as f:
             exec(compile(f.read(), fname, 'exec'), {
                 '__file__': fpath,
                 '__name__': '__main__',
             })
 else:
     import sphinx_rtd_theme
     html_theme = "sphinx_rtd_theme"
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
 exec(compile(open('../../IPython/core/release.py').read(), '../../IPython/core/release.py', 'exec'),iprelease)
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.intersphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
     'sphinx.ext.napoleon',  # to preprocess docstrings
     'github',  # for easy GitHub links
     'magics',
 ]
 
 if ON_RTD:
     # Remove extensions not currently supported on RTD
     extensions.remove('matplotlib.sphinxext.only_directives')
     extensions.remove('matplotlib.sphinxext.mathmpl')
     extensions.remove('matplotlib.sphinxext.plot_directive')
     extensions.remove('IPython.sphinxext.ipython_directive')
     extensions.remove('IPython.sphinxext.ipython_console_highlighting')
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 def is_stable(extra):
     for ext in {'dev', 'b', 'rc'}:
         if ext in extra:
             return False
     return True
 
 if is_stable(iprelease['_version_extra']):
     tags.add('ipystable')
 else:
     tags.add('ipydev')
     rst_prolog = """
     .. warning::
 
         This documentation is for a development version of IPython. There may be
         significant differences from the latest stable release.
 
     """
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = 'The IPython Development Team'
 
 # ghissue config
 github_project_url = "https://github.com/ipython/ipython"
 
 # numpydoc config
 numpydoc_show_class_members = False # Otherwise Sphinx emits thousands of warnings
 numpydoc_class_members_toctree = False
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The full version, including alpha/beta/rc tags.
 release = "%s" % iprelease['version']
 # Just the X.Y.Z part, no '-dev'
 version = iprelease['version'].split('-', 1)[0]
 
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
 # Exclude these glob-style patterns when looking for source files. They are
 # relative to the source/ directory.
 exclude_patterns = ['whatsnew/pr']
 
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # Set the default role so we can use `foo` instead of ``foo``
 default_role = 'literal'
 
 # Options for HTML output
 # -----------------------
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
 # html_style = 'default.css'
-# html_favicon = 'favicon.ico'
+
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+# Favicon needs the directory name
 html_favicon = '_static/favicon.ico'
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 html_additional_pages = {
     'interactive/htmlnotebook': 'notebook_redirect.html',
     'interactive/notebook': 'notebook_redirect.html',
     'interactive/nbconvert': 'notebook_redirect.html',
     'interactive/public_server': 'notebook_redirect.html',
 }
 
 # If false, no module index is generated.
 #html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ipythondoc'
 
 intersphinx_mapping = {'python': ('http://docs.python.org/3/', None),
                        'rpy2': ('http://rpy.sourceforge.net/rpy2/doc-2.4/html/', None),
                        'traitlets': ('http://traitlets.readthedocs.io/en/latest/', None),
                        'jupyterclient': ('http://jupyter-client.readthedocs.io/en/latest/', None),
                        'ipyparallel': ('http://ipyparallel.readthedocs.io/en/latest/', None),
                        'jupyter': ('http://jupyter.readthedocs.io/en/latest/', None),
                       }
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
 latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 
 latex_documents = [
     ('index', 'ipython.tex', 'IPython Documentation',
      u"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      u"Brian E. Granger", 'manual', True)
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 latex_use_modindex = True
 
 
 # Options for texinfo output
 # --------------------------
 
 texinfo_documents = [
   (master_doc, 'ipython', 'IPython Documentation',
    'The IPython Development Team',
    'IPython',
    'IPython Documentation',
    'Programming',
    1),
 ]
 
 modindex_common_prefix = ['IPython.']
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease

docs/source/coredev/release_process.rst

@@ -1,193 +1,193
 .. _release_process:
 
 =======================
 IPython release process
 =======================
 
 This document contains the process that is used to create an IPython release.
 
 Conveniently, the `release` script in the `tools` directory of the `IPython`
 repository automates most of the release process. This document serves as a
 handy reminder and checklist for the release manager.
 
 1. Set Environment variables
 ----------------------------
 
 Set environment variables to document previous release tag, current
 release milestone, current release version, and git tag::
 
     PREV_RELEASE=4.0.0
     MILESTONE=4.1
     VERSION=4.1.0
     BRANCH=master
 
 These variables may be used later to copy/paste as answers to the script
 questions instead of typing the appropriate command when the time comes. These
 variables are not used by the scripts directly; therefore, there is no need to
 `export` the variables.
 
 2. Create GitHub stats and finish release note
 ----------------------------------------------
 
 .. note::
 
     Before generating the GitHub stats, verify that all closed issues and
     pull requests have `appropriate milestones <https://github.com/ipython/ipython/wiki/Dev%3A-GitHub-workflow#milestones>`_.
     `This search <https://github.com/ipython/ipython/issues?q=is%3Aclosed+no%3Amilestone+is%3Aissue>`_
     should return no results before creating the GitHub stats.
 
 If a major release:
 
     - merge any pull request notes into what's new::
 
           python tools/update_whatsnew.py
 
     - update `docs/source/whatsnew/development.rst`, to ensure it covers
       the major release features
     - move the contents of `development.rst` to `versionX.rst` where `X` is
       the numerical release version
     - generate summary of GitHub contributions, which can be done with::
 
           python tools/github_stats.py --milestone $MILESTONE > stats.rst
 
       which may need some manual cleanup of `stats.rst`. Add the cleaned
       `stats.rst` results to `docs/source/whatsnew/github-stats-X.rst` where
       `X` is the numerical release version. If creating a major release, make
       a new `github-stats-X.rst` file; if creating a minor release, the
       content from `stats.rst` may simply be added to the top of an existing
       `github-stats-X.rst` file.
 
 To find duplicates and update `.mailmap`, use::
 
     git log --format="%aN <%aE>" $PREV_RELEASE... | sort -u -f
 
 3. Make sure the repository is clean
 ------------------------------------
 
 of any file that could be problematic.
    Remove all non-tracked files with:
 
    .. code::
 
        git clean -xfdi
 
    This will ask for confirmation before removing all untracked files. Make
    sure the ``dist/`` folder is clean to avoid any stale builds from
    previous build attempts.
 
 
 4. Update the release version number
 ------------------------------------
 
 Edit `IPython/core/release.py` to have the current version.
 
 in particular, update version number and ``_version_extra`` content in
 ``IPython/core/release.py``.
 
 Make sure the version number matches pep440, in particular, `rc` and `beta` are
 not separated by `.` or the `sdist` and `bdist` will appear as different
 releases. For example, a valid version number for a release candidate (rc)
 release is: ``1.3rc1``. Notice that there is no separator between the '3' and
 the 'r'. Check the environment variable `$VERSION` as well. 
 
 
-Comment remove the `developpement` entry in `whatsnew/index.rst`. TODO, figure
+Comment remove the `development` entry in `whatsnew/index.rst`. TODO, figure
 out how to make that automatic. 
 
 5. Run the `tools/build_release` script
 ---------------------------------------
 
 Running `tools/build_release` does all the file checking and building that
 the real release script will do. This makes test installations, checks that
 the build procedure runs OK, and tests other steps in the release process.
 
 The `build_release` script will in particular verify that the version number
 match PEP 440, in order to avoid surprise at the time of build upload.
 
 We encourage creating a test build of the docs as well.
 
 6. Create and push the new tag
 ------------------------------
 
 Commit the changes to release.py::
 
     git commit -am "release $VERSION"
     git push origin $BRANCH
 
 Create and push the tag::
 
     git tag -am "release $VERSION" "$VERSION"
     git push origin --tags
 
 Update release.py back to `x.y-dev` or `x.y-maint`, and re-add the
-`developpement` entry in `docs/source/whatsnew/index.rst` and push::
+`development` entry in `docs/source/whatsnew/index.rst` and push::
 
     git commit -am "back to development"
     git push origin $BRANCH
 
 7. Get a fresh clone
 --------------------
 
 Get a fresh clone of the tag for building the release::
 
     cd /tmp
     git clone --depth 1 https://github.com/ipython/ipython.git -b "$VERSION"
 
 8. Run the release script
 -------------------------
 
 Run the `release` script, this step requires having a current wheel, Python >=3.4 and Python 2.7.::
 
     cd tools && ./release
 
 This makes the tarballs, zipfiles, and wheels, and put them under the `dist/`
 folder. Be sure to test the ``wheel`` and the ``sdist`` locally before uploading
 them to PyPI. 
 
 Use the following to actually upload the result of the build:
 
     ./release upload
 
 It should posts them to ``archive.ipython.org`` and registers the release
 with PyPI if you have the various authorisations. 
 
 You might need to use `twine <https://github.com/pypa/twine>`_ (`twine upload
 dist/*`) manually to actually upload on PyPI. Unlike setuptools, twine is able
 to upload packages over SSL.
 
 
 9. Draft a short release announcement
 -------------------------------------
 
 The announcement should include:
 
 - release highlights
 - a link to the html version of the *What's new* section of the documentation
 - a link to upgrade or installation tips (if necessary)
 
 Post the announcement to the mailing list and or blog, and link from Twitter.
 
 10. Update milestones on GitHub
 -------------------------------
 
 These steps will bring milestones up to date:
 
 - close the just released milestone
 - open a new milestone for the next release (x, y+1), if the milestone doesn't
   exist already
 
 11. Update the IPython website
 ------------------------------
 
 The IPython website should document the new release:
 
 - add release announcement (news, announcements)
 - update current version and download links
 - update links on the documentation page (especially if a major release)
 
 12. Celebrate!
 --------------
 
 Celebrate the release and please thank the contributors for their work. Great
 job!
 

docs/source/index.rst

@@ -1,110 +1,111
 .. _introduction:
 
 =====================
 IPython Documentation
 =====================
 
 .. htmlonly::
 
    :Release: |release|
    :Date: |today|
 
 Welcome to the official IPython documentation
 
 IPython provides a rich toolkit to help you make the most out of using Python
 interactively.  Its main components are:
 
 * A powerful interactive Python shell
+
 * A `Jupyter <http://jupyter.org/>`_ kernel to work with Python code in Jupyter
   notebooks and other interactive frontends.
 
 The enhanced interactive Python shells and kernel have the following main
 features:
 
 * Comprehensive object introspection.
 
 * Input history, persistent across sessions.
 
 * Caching of output results during a session with automatically generated
   references.
 
 * Extensible tab completion, with support by default for completion of python
   variables and keywords, filenames and function keywords.
 
 * Extensible system of 'magic' commands for controlling the environment and
   performing many tasks related either to IPython or the operating system.
 
 * A rich configuration system with easy switching between different setups
   (simpler than changing $PYTHONSTARTUP environment variables every time).
 
 * Session logging and reloading.
 
 * Extensible syntax processing for special purpose situations.
 
 * Access to the system shell with user-extensible alias system.
 
 * Easily embeddable in other Python programs and GUIs.
 
 * Integrated access to the pdb debugger and the Python profiler.
 
 
 The Command line interface inherit all the above functionality and posses 
  
-* real multiline editting.
+* real multi-line editing.
  
 * syntax highlighting as you type
 
-* intgration with command line editor for a better workflow. 
+* integration with command line editor for a better workflow.
 
 The kernel also have its share of feature, when used with a compatible frontend
 it allows for:
 
 * rich display system for object allowing to display Html, Images, Latex,Sounds
   Video.
 
-* interactive widgets with the use of the ``ipywigets`` package. 
+* interactive widgets with the use of the ``ipywidgets`` package.
 
 
 This documentation will walk through most of the features of the IPython
 command line and kernel, as well as describe the internals mechanisms in order
 to improve your Python workflow.
 
 You can always find the table of content for this documentation in the left
 sidebar, allowing you to come back on previous section if needed, or skip ahead. 
 
 
 The latest development version is always available from IPython's `GitHub
 repository <http://github.com/ipython/ipython>`_.
 
 
 
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    self
    overview
    whatsnew/index
    install/index
    interactive/index
    config/index
    development/index
    coredev/index
    api/index
    about/index
 
 .. seealso::
 
    `Jupyter documentation <http://jupyter.readthedocs.io/en/latest/>`__
      The Notebook code and many other pieces formerly in IPython are now parts
      of Project Jupyter.
    `ipyparallel documentation <http://ipyparallel.readthedocs.io/en/latest/>`__
      Formerly ``IPython.parallel``.
 
 
 .. htmlonly::
    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`
 

docs/source/install/index.rst

@@ -1,60 +1,58
 .. _install_index:
 
 ============
 Installation
 ============
 
 .. toctree::
    :maxdepth: 3
    :hidden:
 
 
    install
    kernel_install
 
 
 
-This sections will guide you into `installing IPython itself <install>`_, and
-installing `kernels for jupyter <kernel_install>`_ if you are working with
-multiple version of Python, or multiple environments. 
-
-To know more, head to the next section. 
+This sections will guide you through `installing IPython itself <install>`_, and
+installing `kernels for Jupyter <kernel_install>`_ if you wish to work with
+multiple version of Python, or multiple environments.
 
 
 Quick install reminder
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Here is a quick reminder of the various commands needed if you are already
-familiar with IPython and are just searching to refresh your memory:
+Here is a quick reminder of the commands needed for installation if you are
+already familiar with IPython and are just searching to refresh your memory:
 
 Install IPython:
 
 .. code-block:: bash
 
     $ pip install ipython
 
 
 Install and register an IPython kernel with Jupyter:
 
 
 .. code-block:: bash
 
     $ python -m pip install ipykernel
 
     $ python -m ipykernel install [--user] [--name <machine-readable-name>] [--display-name <"User Friendly Name">]
 
 for more help see 
 
 .. code-block:: bash
     
     $ python -m ipykernel install  --help
     
 
 
 .. seealso::
 
    `Installing Jupyter <http://jupyter.readthedocs.io/en/latest/install.html>`__
      The Notebook, nbconvert, and many other former pieces of IPython are now
      part of Project Jupyter.
 
 

docs/source/install/install.rst

@@ -1,131 +1,132
 Installing IPython
 ==================
 
 
 IPython requires Python 2.7 or ≥ 3.3.
 
 
 Quick Install 
 -------------
 
 With ``pip`` already installed :
 
 .. code-block:: bash
 
     $ pip install ipython
 
-This should install IPython as well as all the other dependency required. 
+This installs IPython as well as its dependencies.
 
-If you try to use IPython with notebooks or the Qt console, you should also install
-``jupyter``.
+If you want to use IPython with notebooks or the Qt console, you should also
+install Jupyter ``pip install jupyter``.
 
 
 
 Overview
 --------
 
 This document describes in detail the steps required to install IPython.
 For a few quick ways to get started with package managers or full Python distributions,
 see `the install page <http://ipython.org/install.html>`_ of the IPython website.
 
 Please let us know if you have problems installing IPython or any of its dependencies.
 
 IPython and most dependencies should be installed via :command:`pip`.
 In many scenarios, this is the simplest method of installing Python packages.
 More information about :mod:`pip` can be found on
 `its PyPI page <https://pip.pypa.io>`__.
 
 
 More general information about installing Python packages can be found in
 `Python's documentation <http://docs.python.org>`_.
 
 
 Installing IPython itself
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 IPython requires several dependencies to work correctly, it is not recommended
-to install IPython and all it's dependencies manually as this can be quite long and trouble some. 
-You should likely use the python package manager ``pip`` 
+to install IPython and all its dependencies manually as this can be quite long and troublesome.
+You should use the python package manager ``pip``.
 
 Installation using pip
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Make sure you have the latest version of :mod:`pip` ( the Python package
+Make sure you have the latest version of :mod:`pip` (the Python package
 manager) installed. If you do not, head to `Pip documentation
-<https://pip.pypa.io/en/stable/installing/>`_ and install it first. 
+<https://pip.pypa.io/en/stable/installing/>`_ and install :mod:`pip` first.
 
 The quickest way to get up and running with IPython is to install it with pip:
 
 .. code-block:: bash
 
     $ pip install ipython
 
 That's it.
 
 
 Installation from source
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you don't want to use :command:`pip`, or don't have it installed,
 grab the latest stable tarball of IPython `from PyPI
 <https://pypi.python.org/pypi/ipython>`__.  Then do the following:
 
 .. code-block:: bash
 
     $ tar -xzf ipython.tar.gz
     $ cd ipython
     $ pip install .
 
 Do not invoke ``setup.py`` directly as this can have undesirable consequences for further upgrades. 
 Try to also avoid any usage of ``easy_install`` that can have similar undesirable consequences.
 
 If you are installing to a location (like ``/usr/local``) that requires higher
 permissions, you may need to run the last command with :command:`sudo`. You can
-also install in user specific location by using the ``--user`` flag in conjunction with pip
+also install in user specific location by using the ``--user`` flag in conjunction with pip.
 
-To can run IPython's test suite, use the :command:`iptest` command from outside of the IPython source tree:
+To run IPython's test suite, use the :command:`iptest` command from outside of the IPython source tree:
 
 .. code-block:: bash
 
     $ iptest
 
 
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is also possible to install the development version of IPython from our
 `Git <http://git-scm.com/>`_ source code repository.  To do this you will
 need to have Git installed on your system.  Then do:
 
 .. code-block:: bash
 
     $ git clone https://github.com/ipython/ipython.git
     $ cd ipython
     $ pip install .
 
 Some users want to be able to follow the development branch as it changes.
 With :mod:`pip` installed, you can replace the last step by:
 
 .. code-block:: bash
 
     $ pip install -e .
 
 This creates links in the right places and installs the command line script to
 the appropriate location. 
 
 Then, if you want to update your IPython at any time, do:
 
 .. code-block:: bash
 
     $ git pull
 
 .. _dependencies:
 
 Dependencies
 ~~~~~~~~~~~~
 
 IPython relies on a number of other Python packages. Installing using a package
 manager like pip or conda will ensure the necessary packages are installed. If
 you install manually, it's up to you to make sure dependencies are installed.
-They're not listed here, because they may change from release to release, and
-depending on platform so a static list will inevitably get out of date.
+They're not listed here since a static list would inevitably fall out of date as
+dependencies may change from release to release and also vary depending on
+the platform.

docs/source/overview.rst

@@ -1,296 +1,296
 .. _overview:
 
 ========
 Overview
 ========
 
 One of Python's most useful features is its interactive interpreter.
 It allows for very fast testing of ideas without the overhead of
 creating test files as is typical in most programming languages.
 However, the interpreter supplied with the standard Python distribution
 is somewhat limited for extended interactive use.
 
 The goal of IPython is to create a comprehensive environment for
 interactive and exploratory computing.  To support this goal, IPython
 has three main components:
 
 * An enhanced interactive Python shell.
 
 * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
   allows for multiple clients to connect to a computation kernel, most notably
   the web-based notebook provided with `Jupyter <https://jupyter.org>`_.
 
 * An architecture for interactive parallel computing now part of the
   `ipyparallel` package.
 
 All of IPython is open source (released under the revised BSD license).
 
 Enhanced interactive Python shell
 =================================
 
 IPython's interactive shell (:command:`ipython`), has the following goals,
 amongst others:
 
 1. Provide an interactive shell superior to Python's default. IPython
    has many features for tab-completion, object introspection, system shell
    access, command history retrieval across sessions, and its own special
    command system for adding functionality when working interactively. It
    tries to be a very efficient environment both for Python code development
    and for exploration of problems using Python objects (in situations like
    data analysis).
   
 2. Serve as an embeddable, ready to use interpreter for your own
    programs. An interactive IPython shell can be started with a single call
    from inside another program, providing access to the current namespace.
    This can be very useful both for debugging purposes and for situations
    where a blend of batch-processing and interactive exploration are needed.
   
 3. Offer a flexible framework which can be used as the base
    environment for working with other systems, with Python as the underlying
    bridge language. Specifically scientific environments like Mathematica,
    IDL and Matlab inspired its design, but similar ideas can be
    useful in many fields.
   
 4. Allow interactive testing of threaded graphical toolkits. IPython
    has support for interactive, non-blocking control of GTK, Qt, WX, GLUT, and
    OS X applications via special threading flags. The normal Python
    shell can only do this for Tkinter applications.
 
 Main features of the interactive shell
 --------------------------------------
 
 * Dynamic object introspection. One can access docstrings, function
   definition prototypes, source code, source files and other details
   of any object accessible to the interpreter with a single
   keystroke (:samp:`?`, and using :samp:`??` provides additional detail).
   
 * Searching through modules and namespaces with :samp:`*` wildcards, both
   when using the :samp:`?` system and via the :samp:`%psearch` command.
 
 * Completion in the local namespace, by typing :kbd:`TAB` at the prompt.
   This works for keywords, modules, methods, variables and files in the
   current directory. This is supported via the ``prompt_toolkit`` library.
   Custom completers can be implemented easily for different purposes
   (system commands, magic arguments etc.)
 
 * Numbered input/output prompts with command history (persistent
   across sessions and tied to each profile), full searching in this
   history and caching of all input and output.
 
 * User-extensible 'magic' commands. A set of commands prefixed with
   :samp:`%`  or :samp:`%%` is available for controlling IPython itself and provides
   directory control, namespace information and many aliases to
   common system shell commands.
 
 * Alias facility for defining your own system aliases.
 
 * Complete system shell access. Lines starting with :samp:`!` are passed
   directly to the system shell, and using :samp:`!!` or :samp:`var = !cmd` 
   captures shell output into python variables for further use.
 
 * The ability to expand python variables when calling the system shell. In a
   shell command, any python variable prefixed with :samp:`$` is expanded. A
   double :samp:`$$` allows passing a literal :samp:`$` to the shell (for access
   to shell and environment variables like :envvar:`PATH`).
 
 * Filesystem navigation, via a magic :samp:`%cd` command, along with a
   persistent bookmark system (using :samp:`%bookmark`) for fast access to
   frequently visited directories.
 
 * A lightweight persistence framework via the :samp:`%store` command, which
   allows you to save arbitrary Python variables. These get restored
   when you run the :samp:`%store -r` command.
 
 * Automatic indentation and highlighting of code as you type (through the
   `prompt_toolkit` library).
 
 * Macro system for quickly re-executing multiple lines of previous
   input with a single name via the :samp:`%macro` command. Macros can be
   stored persistently via :samp:`%store` and edited via :samp:`%edit`.
 
 * Session logging (you can then later use these logs as code in your
   programs). Logs can optionally timestamp all input, and also store
   session output (marked as comments, so the log remains valid
   Python source code).
 
 * Session restoring: logs can be replayed to restore a previous
   session to the state where you left it.
 
 * Verbose and colored exception traceback printouts. Easier to parse
   visually, and in verbose mode they produce a lot of useful
   debugging information (basically a terminal version of the cgitb
   module).
 
 * Auto-parentheses via the :samp:`%autocall` command: callable objects can be
   executed without parentheses: :samp:`sin 3` is automatically converted to
   :samp:`sin(3)`
 
 * Auto-quoting: using :samp:`,`, or :samp:`;` as the first character forces
   auto-quoting of the rest of the line: :samp:`,my_function a b` becomes
   automatically :samp:`my_function("a","b")`, while :samp:`;my_function a b`
   becomes :samp:`my_function("a b")`.
 
 * Extensible input syntax. You can define filters that pre-process
   user input to simplify input in special situations. This allows
   for example pasting multi-line code fragments which start with
   :samp:`>>>` or :samp:`...` such as those from other python sessions or the
   standard Python documentation.
 
 * Flexible :ref:`configuration system <config_overview>`. It uses a
   configuration file which allows permanent setting of all command-line
   options, module loading, code and file execution. The system allows
   recursive file inclusion, so you can have a base file with defaults and
   layers which load other customizations for particular projects.
 
 * Embeddable. You can call IPython as a python shell inside your own
   python programs. This can be used both for debugging code or for
   providing interactive abilities to your programs with knowledge
   about the local namespaces (very useful in debugging and data
   analysis situations).
 
 * Easy debugger access. You can set IPython to call up an enhanced version of
   the Python debugger (pdb) every time there is an uncaught exception. This
   drops you inside the code which triggered the exception with all the data
   live and it is possible to navigate the stack to rapidly isolate the source
   of a bug. The :samp:`%run` magic command (with the :samp:`-d` option) can run
   any script under pdb's control, automatically setting initial breakpoints for
   you.  This version of pdb has IPython-specific improvements, including
   tab-completion and traceback coloring support. For even easier debugger
   access, try :samp:`%debug` after seeing an exception.
 
 * Profiler support. You can run single statements (similar to
   :samp:`profile.run()`) or complete programs under the profiler's control.
   While this is possible with standard cProfile or profile modules,
   IPython wraps this functionality with magic commands (see :samp:`%prun`
   and :samp:`%run -p`) convenient for rapid interactive work.
 
 * Simple timing information. You can use the :samp:`%timeit` command to get
   the execution time of a Python statement or expression. This machinery is
   intelligent enough to do more repetitions for commands that finish very
   quickly in order to get a better estimate of their running time. 
 
 .. sourcecode:: ipython
 
     In [1]: %timeit 1+1
     10000000 loops, best of 3: 25.5 ns per loop
 
     In [2]: %timeit [math.sin(x) for x in range(5000)]
     1000 loops, best of 3: 719 µs per loop
 
 .. 
 
   To get the timing information for more than one expression, use the
   :samp:`%%timeit` cell magic command.
   
 
 * Doctest support. The special :samp:`%doctest_mode` command toggles a mode
   to use doctest-compatible prompts, so you can use IPython sessions as
   doctest code. By default, IPython also allows you to paste existing
   doctests, and strips out the leading :samp:`>>>` and :samp:`...` prompts in
   them.
 
 .. _ipythonzmq:
 
 Decoupled two-process model
 ==============================
 
 IPython has abstracted and extended the notion of a traditional
 *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation*
 into its own process. We call this process a **kernel**: it receives execution
 instructions from clients and communicates the results back to them.
 
 This decoupling allows us to have several clients connected to the same
 kernel, and even allows clients and kernels to live on different machines.
 With the exclusion of the traditional single process terminal-based IPython
 (what you start if you run ``ipython`` without any subcommands), all
 other IPython machinery uses this two-process model. Most of this is now part
 of the `Jupyter` project, whis includes ``jupyter console``,  ``jupyter
 qtconsole``, and ``jupyter notebook``.
 
 As an example, this means that when you start ``jupyter qtconsole``, you're
 really starting two processes, a kernel and a Qt-based client can send
 commands to and receive results from that kernel. If there is already a kernel
 running that you want to connect to, you can pass the  ``--existing`` flag
 which will skip initiating a new kernel and connect to the most recent kernel,
 instead. To connect to a specific kernel once you have several kernels
 running, use the ``%connect_info`` magic to get the unique connection file,
 which will be something like ``--existing kernel-19732.json`` but with
 different numbers which correspond to the Process ID of the kernel.
 
 You can read more about using `jupyter qtconsole 
 <http://jupyter.org/qtconsole/>`_, and
-`ipython notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`_. There 
+`jupyter notebook <http://jupyter-notebook.readthedocs.io/en/latest/>`_. There
 is also a :ref:`message spec <messaging>` which documents the protocol for 
 communication between kernels
 and clients.
 
 .. seealso::
     
     `Frontend/Kernel Model`_ example notebook
 
 
 Interactive parallel computing
 ==============================
 
 .. note::
     
     This functionality is optional and now part of the `ipyparallel
     <http://ipyparallel.readthedocs.io/>`_ project.
 
 Increasingly, parallel computer hardware, such as multicore CPUs, clusters and
 supercomputers, is becoming ubiquitous. Over the last several years, we have
 developed an architecture within IPython that allows such hardware to be used
 quickly and easily from Python. Moreover, this architecture is designed to
 support interactive and collaborative parallel computing.
 
 The main features of this system are:
 
 * Quickly parallelize Python code from an interactive Python/IPython session.
 
 * A flexible and dynamic process model that be deployed on anything from 
   multicore workstations to supercomputers.
 
 * An architecture that supports many different styles of parallelism, from
   message passing to task farming.  And all of these styles can be handled
   interactively.
 
 * Both blocking and fully asynchronous interfaces.
 
 * High level APIs that enable many things to be parallelized in a few lines
   of code.
 
 * Write parallel code that will run unchanged on everything from multicore
   workstations to supercomputers.
 
 * Full integration with Message Passing libraries (MPI).
 
 * Capabilities based security model with full encryption of network connections.
 
 * Share live parallel jobs with other users securely.  We call this
   collaborative parallel computing.
 
 * Dynamically load balanced task farming system.
 
 * Robust error handling.  Python exceptions raised in parallel execution are
   gathered and presented to the top-level code.
 
 For more information, see our :ref:`overview <parallel_index>` of using IPython
 for parallel computing.
 
 Portability and Python requirements
 -----------------------------------
 
 As of the 2.0 release, IPython works with Python 2.7 and 3.3 or above.
 Version 1.0 additionally worked with Python 2.6 and 3.2.
 Version 0.12 was the first version to fully support Python 3.
 
 IPython is known to work on the following operating systems:
 
 	* Linux
 	* Most other Unix-like OSs (AIX, Solaris, BSD, etc.)
 	* Mac OS X
 	* Windows (CygWin, XP, Vista, etc.)
 
 See :ref:`here <install_index>` for instructions on how to install IPython.
 
 .. include:: links.txt

docs/source/whatsnew/version5.rst

@@ -1,164 +1,165
 ============
  5.x Series
 ============
 
 IPython 5.0
 ===========
 
 Released June, 2016
 
 IPython 5.0 now uses `prompt-toolkit` for the command line interface, thus
 allowing real multi-line editing and syntactic coloration as you type.
 
 
 When using IPython as a subprocess, like for emacs inferior-shell, IPython can
 be started with --simple-prompt flag, which will bypass the prompt_toolkit
 input layer. In this mode completion, prompt color and many other features are
 disabled.
 
 Backwards incompatible changes
 ------------------------------
 
 
 The `install_ext magic` function which was deprecated since 4.0 have now been deleted.
 You can still distribute and install extension as packages on PyPI.
 
 Update IPython event triggering to ensure callback registration and
 unregistration only affects the set of callbacks the *next* time that event is
 triggered. See :ghissue:`9447` and :ghpull:`9453`.
 
 This is a change to the existing semantics, wherein one callback registering a
 second callback when triggered for an event would previously be invoked for
 that same event.
 
 Integration with pydb has been removed since pydb development has been stopped
 since 2012, and pydb is not installable from PyPI
 
 
 
 Replacement of readline in TerminalInteractiveShell and PDB
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 IPython 5.0 now uses ``prompt_toolkit``. The
 ``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses
 ``prompt_toolkit``. It is an almost complete rewrite, so many settings have
 thus changed or disappeared. The class keep the same name to avoid breaking
 user configuration for the options which names is unchanged.
 
 The usage of ``prompt_toolkit`` is accompanied by a complete removal of all
 code, using ``readline``. A particular effect of not using `readline` anymore
 is that `.inputrc` settings are note effective anymore. Options having similar
 effects have likely been replaced by a configuration option on IPython itself
 (e.g: vi input mode).
 
 The `PromptManager` class have been removed, and the prompt machinery simplified.
 See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts.
 
 .. note::
 
     During developement and beta cycle, ``TerminalInteractiveShell`` was
     temporarly moved to ``IPtyhon.terminal.ptshell``.
 
 
 Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug`
 and `%pdb` magic which do not use readline anymore either.
 
 The color handling has been slightly changed and is now exposed
 through, in particular the colors of prompts and as you type
 highlighting can be affected by :
 ``TerminalInteractiveShell.highlight_style``. With default
 configuration the ``--colors`` flag and ``%colors`` magic behavior
 should be mostly unchanged. See the `colors <termcolour>`_ section of
 our documentation
 
 Provisional Changes
 -------------------
 
 Provisional changes are in experimental functionality that may, or may not make
 it to future version of IPython, and which API may change without warnings.
 Activating these feature and using these API is at your own risk, and may have
 security implication for your system, especially if used with the Jupyter notebook,
 
 When running via the Jupyter notebook interfaces, or other compatible client,
 you can enable rich documentation experimental functionality:
 
 When the ``docrepr`` package is installed setting the boolean flag
 ``InteractiveShell.sphinxify_docstring`` to ``True``, will process the various
 object through sphinx before displaying them (see the ``docrepr`` package
 documentation for more information.
 
 You need to also enable the IPython pager display rich HTML representation
 using the ``InteractiveShell.enable_html_pager`` boolean configuration option.
 As usual you can set these configuration options globally in your configuration
 files, alternatively you can turn them on dynamically using the following
 snippet:
 
 .. code-block:: python
 
     ip = get_ipython()
     ip.sphinxify_docstring = True
     ip.enable_html_pager = True
 
 
 You can test the effect of various combinations of the above configuration in
 the Jupyter notebook, with things example like :
 
 .. code-block:: ipython
 
     import numpy as np
     np.histogram?
 
 
 This is part of an effort to make Documentation in Python richer and provide in
 the long term if possible dynamic examples that can contain math, images,
 widgets... As stated above this is nightly experimental feature with a lot of
 (fun) problem to solve. We would be happy to get your feedback and expertise on
 it.
 
 
 Removed Feature
 ---------------
 
 - ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now
   apparently. It has been removed.
 
 
 Deprecated Features
 -------------------
 
-Some deprecated feature, don't forget to enable ``DeprecationWarning`` as error
-of you are using IPython in Continuous Integration setup or in your testing in general:
+Some deprecated features are listed in this section. Don't forget to enable
+``DeprecationWarning`` as an error if you are using IPython in a Continuous
+Integration setup or in your testing in general:
 
 .. code-block:: python
 
     import warnings
     warnings.filterwarnings('error', '.*', DeprecationWarning, module='yourmodule.*')
 
 
-- ``hooks.fix_error_editor`` seem to be unused and is pending deprecation.
+- ``hooks.fix_error_editor`` seems unused and is pending deprecation.
 - `IPython/core/excolors.py:ExceptionColors` is  deprecated.
-- `IPython.core.InteractiveShell:write()` is deprecated, use `sys.stdout` instead.
-- `IPython.core.InteractiveShell:write_err()` is deprecated, use `sys.stderr` instead.
-- The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has now no effects.
-- The `global_ns` keyword argument of IPython Embed was deprecated, and  will now have no effect. Use `module` keyword argument instead.
+- `IPython.core.InteractiveShell:write()` is deprecated; use `sys.stdout` instead.
+- `IPython.core.InteractiveShell:write_err()` is deprecated; use `sys.stderr` instead.
+- The `formatter` keyword argument to `Inspector.info` in `IPython.core.oinspec` has no effect.
+- The `global_ns` keyword argument of IPython Embed was deprecated, and has no effect. Use `module` keyword argument instead.
 
 
 Known Issues:
 -------------
 
 - ``<Esc>`` Key does not dismiss the completer and does not clear the current
   buffer. This is an on purpose modification due to current technical
   limitation. Cf :ghpull:`9572`. Escape the control character which is used
   for other shortcut, and there is no practical way to distinguish. Use Ctr-G
   or Ctrl-C as an alternative.
 
 - Cannot use ``Shift-Enter`` and ``Ctrl-Enter`` to submit code in terminal. cf
   :ghissue:`9587` and :ghissue:`9401`. In terminal there is no practical way to
   distinguish these key sequences from a normal new line return.
 
 - ``PageUp`` and ``pageDown`` do not move through completion menu.
 
 - Color styles might not adapt to terminal emulator themes. This will need new
   version of Pygments to be released, and can be mitigated with custom themes.