Merge pull request #8701 from takluyver/docs-4.0-misc

Docs updates for 4.0

IPython/core/completer.py

@@ -485,7 +485,7 b' def back_unicode_name_matches(text):'
     Note that snowman is not a valid python3 combining character but will be expanded.
     Though it will not recombine back to the snowman character by the completion machinery.
 
-    This will not either back-complete standard sequences like \n, \b ...
+    This will not either back-complete standard sequences like \\n, \\b ...
     
     Used on Python 3 only.
     """

IPython/core/magics/pylab.py

@@ -86,11 +86,11 b' class PylabMagics(Magics):'
 
             In [3]: %matplotlib qt
 
-        You can list the available backends using the -l/--list option
+        You can list the available backends using the -l/--list option::
 
            In [4]: %matplotlib --list
            Available matplotlib backends: ['osx', 'qt4', 'qt5', 'gtk3', 'notebook', 'wx', 'qt', 'nbagg',
-            'gtk', 'tk', 'inline']
+           'gtk', 'tk', 'inline']
         """
         args = magic_arguments.parse_argstring(self.matplotlib, line)
         if args.list:

IPython/paths.py

@@ -1,3 +1,5 b''
+"""Find files and directories which IPython uses.
+"""
 import os.path
 import shutil
 import tempfile

docs/autogen_api.py

@@ -20,54 +20,45 b" if __name__ == '__main__':"
     docwriter.package_skip_patterns += [r'\.external$',
                                         # Extensions are documented elsewhere.
                                         r'\.extensions',
-                                        r'\.config\.profile',
-                                        # Old nbformat versions
-                                        r'\.nbformat\.v[1-2]',
-                                        # Public API for this is in kernel.zmq.eventloops
-                                        r'\.kernel\.zmq\.gui',
                                         # Magics are documented separately
                                         r'\.core\.magics',
+                                        # This isn't API
+                                        r'\.sphinxext',
+                                        # Shims
+                                        r'\.kernel',
                                         ]
 
     # The inputhook* modules often cause problems on import, such as trying to
     # load incompatible Qt bindings. It's easiest to leave them all out. The
-    # main API is in the inputhook module, which is documented.
     docwriter.module_skip_patterns += [ r'\.lib\.inputhook.+',
                                         r'\.ipdoctest',
                                         r'\.testing\.plugin',
-                                        # This just prints a deprecation msg:
-                                        r'\.frontend$',
                                         # Deprecated:
                                         r'\.core\.magics\.deprecated',
                                         # Backwards compat import for lib.lexers
                                         r'\.nbconvert\.utils\.lexers',
                                         # We document this manually.
                                         r'\.utils\.py3compat',
-                                        # These are exposed by nbformat
-                                        r'\.nbformat\.convert',
-                                        r'\.nbformat\.validator',
-                                        r'\.nbformat\.notebooknode',
-                                        # Deprecated
-                                        r'\.nbformat\.current',
-                                        # Exposed by nbformat.vN
-                                        r'\.nbformat\.v[3-4]\.nbbase',
                                         # These are exposed in display
                                         r'\.core\.display',
                                         r'\.lib\.display',
-                                        # This isn't actually a module
-                                        r'\.html\.tasks',
-                                        # This is private
-                                        r'\.html\.allow76'
+                                        # Shims
+                                        r'\.config',
+                                        r'\.consoleapp',
+                                        r'\.frontend$',
+                                        r'\.html',
+                                        r'\.nbconvert',
+                                        r'\.nbformat',
+                                        r'\.parallel',
+                                        r'\.qt',
                                         ]
+    # main API is in the inputhook module, which is documented.
 
     # These modules import functions and classes from other places to expose
     # them as part of the public API. They must have __all__ defined. The
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
-        'IPython.nbformat',
-        'IPython.nbformat.v3',
-        'IPython.nbformat.v4',
         'IPython.display',
     })
     

docs/source/install/install.rst

@@ -1,12 +1,10 b''
 IPython requires Python 2.7 or ≥ 3.3.
 
-.. note::
+.. seealso::
 
-    If you need to use Python 2.6 or 3.2, you can find IPython 1.x
-    `here <http://archive.ipython.org/release/>`__,
-    or get it with pip::
-    
-        pip install 'ipython<2'
+   `Installing Jupyter <http://jupyter.readthedocs.org/en/latest/install.html>`__
+     The Notebook, nbconvert, and many other former pieces of IPython are now
+     part of Project Jupyter.
 
 
 Quickstart
@@ -17,12 +15,10 b' the quickest way to get up and running with IPython is:'
 
 .. code-block:: bash
 
-    $ pip install "ipython[all]"
+    $ pip install ipython
 
-This will download and install IPython and its main optional dependencies for the notebook,
-qtconsole, tests, and other functionality.
-Some dependencies (Qt, PyQt for the QtConsole, pandoc for nbconvert) are not pip-installable,
-and will not be pulled in by pip.
+To use IPython with notebooks or the Qt console, you should also install
+``jupyter``.
 
 To run IPython's test suite, use the :command:`iptest` command:
 
@@ -34,16 +30,10 b" To run IPython's test suite, use the :command:`iptest` command:"
 Overview
 ========
 
-This document describes in detail the steps required to install IPython,
-and its various optional dependencies.
+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.
 
-IPython is organized into a number of subpackages, each of which has its own dependencies.
-All of the subpackages come with IPython, so you don't need to download and
-install them separately.  However, to use a given subpackage, you will need to
-install all of its dependencies.
-
 Please let us know if you have problems installing IPython or any of its dependencies.
 
 IPython and most dependencies can be installed via :command:`pip`.
@@ -84,8 +74,8 b' Installation from source'
 ------------------------
 
 If you don't want to use :command:`pip`, or don't have it installed,
-grab the latest stable build of IPython from `here
-<http://ipython.org/download.html>`_.  Then do the following:
+grab the latest stable tarball of IPython `from PyPI
+<https://pypi.python.org/pypi/ipython>`__.  Then do the following:
 
 .. code-block:: bash
 
@@ -97,7 +87,6 b' 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`.
 
 
-
 Installing the development version
 ----------------------------------
 
@@ -127,51 +116,34 b' Then, if you want to update your IPython at any time, do:'
 
     $ git pull
 
-IPython now uses git submodules to ship its javascript dependencies. If you run 
-IPython from git master, you may need to update submodules once in a while with:
-
-.. code-block:: bash
-
-    $ git submodule update
-
-or
-
-.. code-block:: bash
-
-    $ python setup.py submodule
-
-Another option is to copy `git hooks <https://github.com/ipython/ipython/tree/master/git-hooks>`_
-to your ``./git/hooks/`` directory to ensure that your submodules are up to date on each pull.
+.. _dependencies:
 
+Dependencies
+============
 
-Basic optional 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, so a
+static list will inevitably get out of date.
 
-There are a number of basic optional dependencies that most users will want to
-get.  These are:
-
-* readline (for command line editing, tab completion, etc.)
-* nose (to run the IPython test suite)
-* mock (Python < 3, also for tests)
-
-If you are comfortable installing these things yourself, have at it, otherwise
-read on for more details.
-
-IPython uses several other modules, such as pexpect_ and path.py, if they are
-installed on your system, but it can also use bundled versions from
-:mod:`IPython.external`, so there's no need to install them separately.
+It also has one key non-Python dependency which you may need to install separately.
 
 readline
 --------
 
-As indicated above, on Windows, to get full functionality in the console
-version of IPython, PyReadline is needed.
+IPython's terminal interface relies on readline to provide features like tab
+completion and history navigation. If you only want to use IPython as a kernel
+for Jupyter notebooks and other frontends, you don't need readline.
+
+
+**On Windows**, to get full console functionality, *PyReadline* is required.
 PyReadline is a separate, Windows only implementation of readline that uses
 native Windows calls through :mod:`ctypes`. The easiest way of installing
 PyReadline is you use the binary installer available `here
 <http://pypi.python.org/pypi/pyreadline>`__.
 
-On OS X, if you are using the built-in Python shipped by Apple, you will be
+**On OS X**, if you are using the built-in Python shipped by Apple, you will be
 missing a proper readline implementation as Apple ships instead a library called
 ``libedit`` that provides only some of readline's functionality.  While you may
 find libedit sufficient, we have occasional reports of bugs with it and several
@@ -179,7 +151,8 b' developers who use OS X as their main environment consider libedit unacceptable'
 for productive, regular use with IPython.
 
 Therefore, IPython on OS X depends on the :mod:`gnureadline` module.
-We will *not* consider completion/history problems to be bugs for IPython if you are using libedit.
+We will *not* consider completion/history problems to be bugs for IPython if you
+are using libedit.
 
 To get a working :mod:`readline` module on OS X, do (with :mod:`pip`
 installed):
@@ -201,174 +174,7 b' optional dependencies:'
 
     $ pip install "ipython[terminal]"
 
+**On Linux**, readline is normally installed by default. If not, install it
+from your system package manager. If you are compiling your own Python, make
+sure you install the readline development headers first.
 
-nose
-----
-
-To run the IPython test suite you will need the :mod:`nose` package.  Nose
-provides a great way of sniffing out and running all of the IPython tests.  The
-simplest way of getting nose is to use :command:`pip`:
-
-.. code-block:: bash
-
-    $ pip install nose
-
-Another way of getting this is to do:
-
-.. code-block:: bash
-
-    $ pip install "ipython[test]"
-
-For more installation options, see the `nose website
-<https://nose.readthedocs.org>`_.  
-
-Once you have nose installed, you can run IPython's test suite using the
-iptest command:
-
-.. code-block:: bash
-
-    $ iptest
-
-Dependencies for IPython.parallel (parallel computing)
-======================================================
-
-IPython's inter-process communication uses the PyZMQ_ bindings for the ZeroMQ_ messaging library.
-This is the only dependency for :mod:`IPython.parallel`.
-
-Shortcut:
-
-.. code-block:: bash
-
-    pip install "ipython[parallel]"
-
-or manual
-
-.. code-block:: bash
-
-    pip install pyzmq
-
-PyZMQ provides wheels for current Python on OS X and Windows, so installing pyzmq will typically not require compilation.
-
-IPython.parallel can use SSH tunnels, which require paramiko_ on Windows.
-
-Dependencies for the IPython Qt console
-=======================================
-
-pyzmq_, pygments_, PyQt_ (or PySide_)
-
-Shortcut:
-
-.. code-block:: bash
-
-    pip install "ipython[qtconsole]"
-
-or manual
-
-.. code-block:: bash
-
-    pip install pyzmq pygments
-
-PyQt/PySide are not pip installable, so generally must be installed via system package managers (or conda).
-
-.. _installnotebook:
-
-Dependencies for the IPython HTML notebook
-==========================================
-
-The HTML notebook is a complex web application with quite a few dependencies:
-
-pyzmq_, jinja2_, tornado_, mistune_, jsonschema_, pygments_, terminado_
-
-Shortcut:
-
-.. code-block:: bash
-
-    pip install "ipython[notebook]"
-
-or manual:
-
-.. code-block:: bash
-
-    pip install pyzmq jinja2 tornado mistune jsonschema pygments terminado
-
-The IPython notebook is a notebook-style web interface to IPython and can be
-started with the command ``ipython notebook``.
-
-MathJax
--------
-
-The IPython notebook uses the MathJax_ Javascript library for rendering LaTeX
-in web browsers. Because MathJax is large, we don't include it with
-IPython. Normally IPython will load MathJax from a CDN, but if you have a slow
-network connection, or want to use LaTeX without an internet connection at all,
-you can install MathJax locally.
-
-A quick and easy method is to install it from a python session::
-
-    python -m IPython.external.mathjax
-
-If you need tighter configuration control, you can download your own copy
-of MathJax from http://www.mathjax.org/download/ - use the MathJax-2.0 link.
-When you have the file stored locally, install it with::
-
-    python -m IPython.external.mathjax /path/to/source/mathjax-MathJax-v2.0-20-g07669ac.zip
-
-For unusual needs, IPython can tell you what directory it wants to find MathJax in::
-
-    python -m IPython.external.mathjax -d /some/other/mathjax
-
-By default MathJax will be installed in your ipython directory, but you
-can install MathJax system-wide.  Please refer to the documentation
-of :mod:`IPython.external.mathjax`
-
-Browser Compatibility
----------------------
-
-The IPython notebook is officially supported on the following browsers:
-
-* Chrome ≥ 13
-* Safari ≥ 5
-* Firefox ≥ 6
-
-The is mainly due to the notebook's usage of WebSockets and the flexible box model.
-
-The following browsers are unsupported:
-
-* Safari < 5
-* Firefox < 6
-* Chrome < 13
-* Opera (any): CSS issues, but execution might work
-* Internet Explorer < 10
-* Internet Explorer ≥ 10 (same as Opera)
-
-Using Safari with HTTPS and an untrusted certificate is known to not work (websockets will fail).
-
-
-Dependencies for nbconvert (converting notebooks to various formats)
-====================================================================
-
-For converting markdown to formats other than HTML, nbconvert uses Pandoc_ (1.12.1 or later).
-
-To install pandoc on Linux, you can generally use your package manager::
-
-    sudo apt-get install pandoc
-
-On other platforms, you can get pandoc from `their website <http://johnmacfarlane.net/pandoc/installing.html>`_.
-
-
-.. _ZeroMQ: http://www.zeromq.org
-.. _PyZMQ: https://github.com/zeromq/pyzmq
-.. _paramiko: https://github.com/robey/paramiko
-.. _pygments: http://pygments.org
-.. _pexpect: http://pexpect.readthedocs.org/en/latest/
-.. _Jinja: http://jinja.pocoo.org
-.. _Sphinx: http://sphinx-doc.org
-.. _pandoc: http://johnmacfarlane.net/pandoc
-.. _Tornado: http://www.tornadoweb.org
-.. _MathJax: http://www.mathjax.org
-.. _PyQt: http://www.riverbankcomputing.com/software/pyqt/intro
-.. _PySide: http://qt-project.org/wiki/PySide
-.. _jinja2: http://jinja.pocoo.org/
-.. _mistune: https://github.com/lepture/mistune
-.. _jsonschema: https://github.com/Julian/jsonschema
-.. _terminado: https://github.com/takluyver/terminado

docs/source/interactive/tutorial.rst

@@ -190,6 +190,8 b' Profiles allow you to use IPython for different tasks, keeping separate config'
 files and history for each one. More details in :ref:`the profiles section
 <profiles>`.
 
+.. _startup_files:
+
 Startup Files
 -------------
 

docs/source/whatsnew/github-stats-3.rst

@@ -11,7 +11,7 b' GitHub stats for 2015/02/27 - 2015/04/03 (since 3.0)'
 These lists are automatically generated, and may be incomplete or contain duplicates.
 
 We closed 46 issues and merged 133 pull requests.
-The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.1>`_.
+The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.1>`__.
 
 The following 33 authors contributed 344 commits:
 
@@ -58,7 +58,7 b' GitHub stats for 2014/04/02 - 2015/02/13 (since 2.0)'
 These lists are automatically generated, and may be incomplete or contain duplicates.
 
 We closed 469 issues and merged 925 pull requests.
-The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.0>`_.
+The full list can be seen `on GitHub <https://github.com/ipython/ipython/milestones/3.0>`__.
 
 The following 155 authors contributed 5975 commits.
 

docs/source/whatsnew/version0.11.rst

@@ -253,8 +253,8 b' Twisted is itself a Python library. So while Twisted is a very capable'
 framework, we think ZeroMQ fits our needs much better and we hope you will find
 the change to be a significant improvement in the long run.
 
-Our manual contains :ref:`a full description of how to use IPython for parallel
-computing <parallel_overview>`, and the `tutorial`__ presented by Min
+Our manual contains a full description of how to use IPython for parallel
+computing, and the `tutorial`__ presented by Min
 Ragan-Kelley at the SciPy 2011 conference provides a hands-on complement to the
 reference docs.
 
@@ -287,7 +287,7 b' that assigning values is pure Python assignment. Simple flags exist for'
 commonly used options, these are always prefixed with '--'.
 
 The IPython command-line help has the details of all the options (via
-``ipythyon --help``), but a simple example should clarify things; the ``pylab``
+``ipython --help``), but a simple example should clarify things; the ``pylab``
 flag can be used to start in pylab mode with the qt4 backend::
 
   ipython --pylab=qt

docs/source/whatsnew/version0.13.rst

@@ -283,7 +283,7 b' that provide specialized magics. These typically require additional software'
 to run and must be manually loaded via ``%load_ext <extension name>``, but are
 extremely useful.  The following extensions are provided:
 
-**Cython magics** (extension :ref:`cythonmagic <extensions_cythonmagic>`)
+**Cython magics** (extension ``cythonmagic``)
     This extension provides magics to automatically build and compile Python
     extension modules using the Cython_ language. You must install Cython
     separately, as well as a C compiler, for this to work.  The examples
@@ -425,7 +425,7 b' of the internal execution parts:'
 The parallel tools now default to using ``NoDB`` as the storage backend for
 intermediate results.  This means that the default usage case will have a
 significantly reduced memory footprint, though certain advanced features are
-not available with this backend.  For more details, see :ref:`parallel_db`.
+not available with this backend.
 
 The parallel magics now display all output, so you can do parallel plotting or
 other actions with complex display.  The ``px`` magic has now both line and cell
@@ -530,10 +530,7 b' The directory ``docs/resources`` in the source distribution contains SVG and'
 PNG versions of our file icons, as well as an ``Info.plist.example`` file with
 instructions to install them on Mac OSX.  This is a first draft of our icons,
 and we encourage contributions from users with graphic talent to improve them
-in the future:
-
-.. image:: ../../resources/ipynb_icon_128x128.png
-   :alt:  IPython notebook file icon.
+in the future.
 
 	  
 New top-level `locate` command

tools/github_stats.py

@@ -212,7 +212,7 b' if __name__ == "__main__":'
 
     print("We closed %d issues and merged %d pull requests." % (n_issues, n_pulls))
     if milestone:
-        print("The full list can be seen `on GitHub <https://github.com/%s/milestone/%s>`"
+        print("The full list can be seen `on GitHub <https://github.com/%s/milestone/%s>`__"
             % (project, milestone)
         )