Merge pull request #9668 from Carreau/more-docs

One more pass on the docs.

docs/source/conf.py

@@ -216,12 +216,12 b' html_additional_pages = {'
 # 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),
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None),
+                       'rpy2': ('https://rpy2.readthedocs.io/en/version_2.8.x/', None),
+                       'traitlets': ('https://traitlets.readthedocs.io/en/latest/', None),
+                       'jupyterclient': ('https://jupyter-client.readthedocs.io/en/latest/', None),
+                       'ipyparallel': ('https://ipyparallel.readthedocs.io/en/latest/', None),
+                       'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None),
                       }
 
 # Options for LaTeX output

docs/source/interactive/index.rst

@@ -2,16 +2,28 b''
 Using IPython for interactive work
 ==================================
 
+This section of IPython documentation walk you through most of the IPython
+functionality. You do not need to have any deep knowledge of Python to read this
+tutorial, though some section might make slightly more sens if you have already
+done some work in the REPL.
+
+.. note::
+    
+    Some part of this documentation are more than a decade old so might be out
+    of date, we welcome any report of inacuracy, and Pull Requests that make
+    that up to date.
+
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
    tutorial
-   magics
    plotting
    reference
    shell
    tips
    python-ipython-diff
+   magics
 
 .. seealso::
 

docs/source/interactive/magics.rst

@@ -2,4 +2,22 b''
 Built-in magic commands
 =======================
 
+.. note::
+
+    To Jupyter users: Magics are specific to and provided by the IPython kernel.
+    Whether magics are available on a kernel is a decision that is made by
+    the kernel developer on a per-kernel basis. To work properly, Magics must
+    use a syntax element which is not valid in the underlying language. For
+    example, the IPython kernel uses the `%` syntax element for magics as `%`
+    is not a valid unary operator in Python. While, the syntax element has
+    meaning in other languages.
+
+Here is the help auto generated from the docstrings of all the available magics
+function that IPython ships with. 
+
+You can create an register your own magics with IPython. You can find many user
+defined magics on `PyPI <https://pypi.io>`_. Feel free to publish your own and
+use the ``Framework :: IPython`` trove classifier. 
+
+
 .. include:: magics-generated.txt

docs/source/interactive/plotting.rst

@@ -6,11 +6,11 b' One major feature of the IPython kernel is the ability to display plots that'
 are the output of running code cells. The IPython kernel is designed to work 
 seamlessly with the matplotlib_ plotting library to provide this functionality.
 
-To set this up, before any plotting is performed you must execute the
-``%matplotlib``  :ref:`magic command <magics_explained>`. This performs the
-necessary behind-the-scenes setup for IPython to work correctly hand in hand
-with ``matplotlib``; it does *not*, however, actually execute any Python
-``import`` commands, that is, no names are added to the namespace.
+To set this up, before any plotting or import of matplotlib is performed you
+must execute the ``%matplotlib``  :ref:`magic command <magics_explained>`. This
+performs the necessary behind-the-scenes setup for IPython to work correctly
+hand in hand with ``matplotlib``; it does *not*, however, actually execute any
+Python ``import`` commands, that is, no names are added to the namespace.
 
 If the ``%matplotlib`` magic is called without an argument, the
 output of a plotting command is displayed using the default ``matplotlib``
@@ -25,12 +25,18 b' Jupyter QtConsole. It can be invoked as follows::'
 
   %matplotlib inline
 
-With this backend, the output of plotting commands is displayed *inline*
-within the notebook, directly below the code cell that produced it. The
-resulting plots will then also be stored in the notebook document.
+With this backend, the output of plotting commands is displayed *inline* within
+frontends like the Jupyter notebook, directly below the code cell that produced
+it. The resulting plots will then also be stored in the notebook document.
 
 .. seealso::
 
     `Plotting with Matplotlib`_  example notebook
 
+
+The matplotlib_ library also ships with ``%matplotlib notebook`` command that
+allows interactive figures if your environment allows it.
+
+See the matplotlib_ documentation for more information. 
+
 .. include:: ../links.txt

docs/source/interactive/reference.rst

@@ -11,20 +11,21 b' You start IPython with the command::'
 
     $ ipython [options] files
 
-If invoked with no options, it executes all the files listed in sequence
-and drops you into the interpreter while still acknowledging any options
-you may have set in your ipython_config.py. This behavior is different from
-standard Python, which when called as python -i will only execute one
-file and ignore your configuration setup.
-
-Please note that some of the configuration options are not available at
-the command line, simply because they are not practical here. Look into
-your configuration files for details on those. There are separate configuration
-files for each profile, and the files look like :file:`ipython_config.py` or
+If invoked with no options, it executes all the files listed in sequence and
+exits. If you add the ``-i`` flag, it drops you into the interpreter while still
+acknowledging any options you may have set in your ``ipython_config.py``. This
+behavior is different from standard Python, which when called as python ``-i``
+will only execute one file and ignore your configuration setup.
+
+Please note that some of the configuration options are not available at the
+command line, simply because they are not practical here. Look into your
+configuration files for details on those. There are separate configuration files
+for each profile, and the files look like :file:`ipython_config.py` or
 :file:`ipython_config_{frontendname}.py`.  Profile directories look like
-:file:`profile_{profilename}` and are typically installed in the :envvar:`IPYTHONDIR` directory,
-which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
-resolves to :file:`C:\\Users\\{YourUserName}` in most instances.
+:file:`profile_{profilename}` and are typically installed in the
+:envvar:`IPYTHONDIR` directory, which defaults to :file:`$HOME/.ipython`. For
+Windows users, :envvar:`HOME` resolves to :file:`C:\\Users\\{YourUserName}` in
+most instances.
 
 Command-line Options
 --------------------
@@ -36,11 +37,24 b' alias to control them, but IPython lets you configure all of its objects from'
 the command-line by passing the full class name and a corresponding value; type
 ``ipython --help-all`` to see this full list.  For example::
 
-  ipython --matplotlib qt
+    $ ipython --help-all
+    <...snip...>
+    --matplotlib=<CaselessStrEnum> (InteractiveShellApp.matplotlib)
+        Default: None
+        Choices: ['auto', 'gtk', 'gtk3', 'inline', 'nbagg', 'notebook', 'osx', 'qt', 'qt4', 'qt5', 'tk', 'wx']
+        Configure matplotlib for interactive use with the default matplotlib
+        backend.
+    <...snip...>
+
+
+Indicate that the following::
+
+   $ ipython --matplotlib qt
+
 
 is equivalent to::
 
-  ipython --TerminalIPythonApp.matplotlib='qt'
+   $ ipython --TerminalIPythonApp.matplotlib='qt'
 
 Note that in the second form, you *must* use the equal sign, as the expression
 is evaluated as an actual Python assignment.  While in the above example the
@@ -145,9 +159,9 b' use it:'
 
     /home/fperez/ipython
 
-Line magics, if they return a value, can be assigned to a variable using the syntax
-``l = %sx ls`` (which in this particular case returns the result of `ls` as a python list).
-See :ref:`below <manual_capture>` for more information.
+Line magics, if they return a value, can be assigned to a variable using the
+syntax ``l = %sx ls`` (which in this particular case returns the result of `ls`
+as a python list). See :ref:`below <manual_capture>` for more information.
 
 Type ``%magic`` for more information, including a list of all available magic
 functions at any time and their docstrings. You can also type
@@ -215,15 +229,6 b' The dynamic object information functions (?/??, ``%pdoc``,'
 directly on variables. For example, after doing ``import os``, you can use
 ``os.path.abspath??``.
 
-.. _readline:
-
-Readline-based features
------------------------
-
-These features require the GNU readline library, so they won't work if your
-Python installation lacks readline support. We will first describe the default
-behavior IPython uses, and then how to change it to suit your preferences.
-
 
 Command line completion
 +++++++++++++++++++++++
@@ -313,8 +318,8 b' before logging has been started.'
 System shell access
 -------------------
 
-Any input line beginning with a ! character is passed verbatim (minus
-the !, of course) to the underlying operating system. For example,
+Any input line beginning with a ``!`` character is passed verbatim (minus
+the ``!``, of course) to the underlying operating system. For example,
 typing ``!ls`` will run 'ls' in the current directory.
 
 .. _manual_capture:
@@ -368,9 +373,9 b' system shell commands. These aliases can have parameters.'
 Then, typing ``alias_name params`` will execute the system command 'cmd
 params' (from your underlying operating system).
 
-You can also define aliases with parameters using %s specifiers (one per
+You can also define aliases with parameters using ``%s`` specifiers (one per
 parameter). The following example defines the parts function as an
-alias to the command 'echo first %s second %s' where each %s will be
+alias to the command ``echo first %s second %s`` where each ``%s`` will be
 replaced by a positional parameter to the call to %parts::
 
     In [1]: %alias parts echo first %s second %s
@@ -427,12 +432,14 b' up for editing on the next command line.'
 
 The following variables always exist:
 
-* _i, _ii, _iii: store previous, next previous and next-next previous inputs.
-* In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
-  overwrite In with a variable of your own, you can remake the assignment to the
-  internal list with a simple ``In=_ih``.
+* ``_i``, ``_ii``, ``_iii``: store previous, next previous and next-next
+  previous inputs.
+
+* ``In``, ``_ih`` : a list of all inputs; ``_ih[n]`` is the input from line
+  ``n``. If you overwrite In with a variable of your own, you can remake the
+  assignment to the internal list with a simple ``In=_ih``.
 
-Additionally, global variables named _i<n> are dynamically created (<n>
+Additionally, global variables named ``_i<n>`` are dynamically created (``<n>``
 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
 
 For example, what you typed at prompt 14 is available as ``_i14``, ``_ih[14]``
@@ -443,10 +450,10 b' by printing them out: they print like a clean string, without prompt'
 characters. You can also manipulate them like regular variables (they
 are strings), modify or exec them.
 
-You can also re-execute multiple lines of input easily by using the
-magic :magic:`rerun` or :magic:`macro` functions. The macro system also allows you to re-execute
-previous lines which include magic function calls (which require special
-processing). Type %macro? for more details on the macro system.
+You can also re-execute multiple lines of input easily by using the magic
+:magic:`rerun` or :magic:`macro` functions. The macro system also allows you to
+re-execute previous lines which include magic function calls (which require
+special processing). Type %macro? for more details on the macro system.
 
 A history function :magic:`history` allows you to see any part of your input
 history by printing a range of the _i variables.

docs/source/interactive/tutorial.rst

@@ -34,9 +34,8 b' Tab completion'
 
 Tab completion, especially for attributes, is a convenient way to explore the
 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
-to view the object's attributes (see :ref:`the readline section <readline>` for
-more). Besides Python objects and keywords, tab completion also works on file
-and directory names.
+to view the object's attributes. Besides Python objects and keywords, tab
+completion also works on file and directory names.
 
 Exploring your objects
 ======================
@@ -53,15 +52,19 b' Magic functions'
 
 IPython has a set of predefined 'magic functions' that you can call with a
 command line style syntax.  There are two kinds of magics, line-oriented and
-cell-oriented.  **Line magics** are prefixed with the ``%`` character and work much
-like OS command-line calls: they get as an argument the rest of the line, where
-arguments are passed without parentheses or quotes.  **Cell magics** are
-prefixed with a double ``%%``, and they are functions that get as an argument
-not only the rest of the line, but also the lines below it in a separate
-argument.
+cell-oriented.  **Line magics** are prefixed with the ``%`` character and work
+much like OS command-line calls: they get as an argument the rest of the line,
+where arguments are passed without parentheses or quotes. **Lines magics** can
+return results and can be used in the right hand side of an assignment.  **Cell
+magics** are prefixed with a double ``%%``, and they are functions that get as
+an argument not only the rest of the line, but also the lines below it in a
+separate argument.
 
-The following examples show how to call the builtin :magic:`timeit` magic, both in
-line and cell mode::
+Magics are useful as convenient functions where Python syntax is not the most
+natural one, or when one want to embed invalid python syntax in their work flow. 
+
+The following examples show how to call the builtin :magic:`timeit` magic, both
+in line and cell mode::
 
       In [1]: %timeit range(1000)
       100000 loops, best of 3: 7.76 us per loop
@@ -73,20 +76,23 b' line and cell mode::'
 
 The builtin magics include:
 
-- Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`, :magic:`macro`,
-  :magic:`recall`, etc.
-- Functions which affect the shell: :magic:`colors`, :magic:`xmode`, :magic:`autoindent`,
-  :magic:`automagic`, etc.
-- Other functions such as :magic:`reset`, :magic:`timeit`, :cellmagic:`writefile`, :magic:`load`, or
-  :magic:`paste`.
+- Functions that work with code: :magic:`run`, :magic:`edit`, :magic:`save`,
+  :magic:`macro`, :magic:`recall`, etc.
+
+- Functions which affect the shell: :magic:`colors`, :magic:`xmode`,
+  :magic:`autoindent`, :magic:`automagic`, etc.
+
+- Other functions such as :magic:`reset`, :magic:`timeit`,
+  :cellmagic:`writefile`, :magic:`load`, or :magic:`paste`.
 
-You can always call them using the ``%`` prefix, and if you're calling a line
-magic on a line by itself, you can omit even that::
+You can always call magics using the ``%`` prefix, and if you're calling a line
+magic on a line by itself, as long as the identifier is not defined in your
+namespace, you can omit even that::
 
     run thescript.py
 
-You can toggle this behavior by running the :magic:`automagic` magic.  Cell magics
-must always have the ``%%`` prefix.
+You can toggle this behavior by running the :magic:`automagic` magic.  Cell
+magics must always have the ``%%`` prefix.
 
 A more detailed explanation of the magic system can be obtained by calling
 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
@@ -95,18 +101,20 b' read its docstring. To see all the available magic functions, call'
 
 .. seealso::
 
-    :doc:`magics`
+    The :ref:`magic` section of the documentation goes more in depth into how
+    the magics works and how to define your own, and :doc:`magics` for a list of
+    built-in magics.
 
     `Cell magics`_ example notebook
 
 Running and Editing
 -------------------
 
-The :magic:`run` magic command allows you to run any python script and load all of
-its data directly into the interactive namespace. Since the file is re-read
+The :magic:`run` magic command allows you to run any python script and load all
+of its data directly into the interactive namespace. Since the file is re-read
 from disk each time, changes you make to it are reflected immediately (unlike
-imported modules, which have to be specifically reloaded). IPython also
-includes :ref:`dreload <dreload>`, a recursive reload function.
+imported modules, which have to be specifically reloaded). IPython also includes
+:ref:`dreload <dreload>`, a recursive reload function.
 
 ``%run`` has special flags for timing the execution of your scripts (-t), or
 for running them under the control of either Python's pdb debugger (-d) or
@@ -114,7 +122,9 b' profiler (-p).'
 
 The :magic:`edit` command gives a reasonable approximation of multiline editing,
 by invoking your favorite editor on the spot. IPython will execute the
-code you type in there as if it were typed interactively.
+code you type in there as if it were typed interactively. Note that for
+:magic:`edit` to work, the call to startup your editor has to be a blocking
+call. In a GUI environment, your editor likely will have such an option.
 
 Debugging
 ---------
@@ -122,9 +132,9 b' Debugging'
 After an exception occurs, you can call :magic:`debug` to jump into the Python
 debugger (pdb) and examine the problem. Alternatively, if you call :magic:`pdb`,
 IPython will automatically start the debugger on any uncaught exception. You can
-print variables, see code, execute statements and even walk up and down the
-call stack to track down the true source of the problem. This can be an efficient
-way to develop and debug code, in many cases eliminating the need for print
+print variables, see code, execute statements and even walk up and down the call
+stack to track down the true source of the problem. This can be an efficient way
+to develop and debug code, in many cases eliminating the need for print
 statements or external debugging tools.
 
 You can also step through a program from the beginning by calling
@@ -157,7 +167,7 b' This will take line 3 and lines 18 to 20 from the current session, and lines'
 System shell commands
 =====================
 
-To run any command at the system shell, simply prefix it with !, e.g.::
+To run any command at the system shell, simply prefix it with ``!``, e.g.::
 
     !ping www.bbc.co.uk
     
@@ -169,12 +179,13 b' with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section'
 Define your own system aliases
 ------------------------------
 
-It's convenient to have aliases to the system commands you use most often.
-This allows you to work seamlessly from inside IPython with the same commands
-you are used to in your system shell. IPython comes with some pre-defined
-aliases and a complete system for changing directories, both via a stack (see
-:magic:`pushd`, :magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a history of
-visited directories and allows you to go to any previously visited one.
+It's convenient to have aliases to the system commands you use most often. This
+allows you to work seamlessly from inside IPython with the same commands you are
+used to in your system shell. IPython comes with some pre-defined aliases and a
+complete system for changing directories, both via a stack (see :magic:`pushd`,
+:magic:`popd` and :magic:`dhist`) and via direct :magic:`cd`. The latter keeps a
+history of visited directories and allows you to go to any previously visited
+one.
 
 
 Configuration