major doc update for 1.0 release

ivanov · ivanov · commit 20cd990c6438 · 2013-08-08T17:41:51.000-07:00
- added links to example notebooks on nbviewer
- removde unnecessary file and parts of files
- put old htmlnotebook.html redirect (for Notebook Help urls in 0.13.x)
- moved working_remotely to public_server
- re-arrangement of notebook connection stuff
- more cross-referencing of documentation sections
- made links to magic command explanation in tutorial
- and many more changes...
diff --git a/docs/source/_templates/htmlnotebook.html b/docs/source/_templates/htmlnotebook.html
@@ -0,0 +1,9 @@
+<html>
+    <head>
+        <meta http-equiv="Refresh" content="0; url=notebook.html" />
+        <title>Notebook page has move</title>
+    </head> 
+    <body>
+        <p>The notebook page has moved to  <a href="notebook.html">this link</a>.</p>
+    </body>
+</html>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -157,7 +157,9 @@
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+html_additional_pages = {
+                         'interactive/htmlnotebook': 'htmlnotebook.html',
+}
 
 # If false, no module index is generated.
 #html_use_modindex = True
diff --git a/docs/source/install/install.rst b/docs/source/install/install.rst
@@ -319,7 +319,7 @@ Dependencies for the IPython HTML notebook
 ==========================================
 
 The IPython notebook is a notebook-style web interface to IPython and can be
-started withe command ``ipython notebook``.
+started with the command ``ipython notebook``.
 
 pyzmq
 -----
diff --git a/docs/source/interactive/index.rst b/docs/source/interactive/index.rst
@@ -12,6 +12,6 @@ Using IPython for interactive work
    qtconsole
    notebook
    nbconvert
-   working_remotely
+   public_server
 
 
diff --git a/docs/source/interactive/notebook.rst b/docs/source/interactive/notebook.rst
diff --git a/docs/source/interactive/public_server.rst b/docs/source/interactive/public_server.rst
@@ -1,13 +1,16 @@
 .. _working_remotely.txt
 
-Working remotely
-================
+Running a notebook server
+=========================
 
 
-The IPython Notebook web app is based on a server-client structure. 
-This server uses a two-process kernel architecture based on ZeroMQ_, as well
-as Tornado_ for serving HTTP requests. Other clients may connect to the same 
-underlying IPython kernel; see below.
+The  :ref:`IPython notebook <htmlnotebook>` web-application is based on a
+server-client structure.  This server uses a :ref:`two-process kernel
+architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
+HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
+and is accessible only from `localhost`. This document describes how you can
+:ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
+a public interface <notebook_public_server>`.
 
 .. _ZeroMQ: http://zeromq.org
 
@@ -16,10 +19,10 @@ underlying IPython kernel; see below.
 
 .. _notebook_security:
 
-Security
---------
+Notebook security
+-----------------
 
-You can protect your Notebook server with a simple single password by
+You can protect your notebook server with a simple single password by
 setting the :attr:`NotebookApp.password` configurable. You can prepare a
 hashed password using the function :func:`IPython.lib.security.passwd`:
 
@@ -65,41 +68,15 @@ self-signed.  If you want to have a fully compliant certificate that will not
 raise warnings, it is possible (but rather involved) to obtain one,
 as explained in detail in `this tutorial`__.
 
-.. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-
-secure-sertificate-for-free.ars
+.. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
 	
 Keep in mind that when you enable SSL support, you will need to access the
 notebook server over ``https://``, not over plain ``http://``.  The startup
 message from the server prints this, but it is easy to overlook and think the
 server is for some reason non-responsive.
 
 
-Connecting to an existing kernel
----------------------------------
-
-The notebook server always prints to the terminal the full details of 
-how to connect to each kernel, with messages such as the following::
-
-    [IPKernelApp] To connect another client to this kernel, use:
-    [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
-
-This long string is the name of a JSON file that contains all the port and 
-validation information necessary to connect to the kernel.  You can then, for 
-example, manually start a Qt console connected to the *same* kernel with::
-
-    $ ipython qtconsole --existing 
-    kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
-
-If you have only a single kernel running, simply typing::
-
-    $ ipython qtconsole --existing
-
-will automatically find it. (It will always find the most recently 
-started kernel if there is more than one.)  You can also request this 
-connection data by typing ``%connect_info``; this will print the same 
-file information as well as the content of the JSON data structure it 
-contains.
-
+.. _notebook_public_server:
 
 Running a public notebook server
 --------------------------------
@@ -152,8 +129,8 @@ modifying ``ipython_notebook_config.py``)::
 Using a different notebook store
 --------------------------------
 
-By default, the Notebook app stores the notebook documents that it saves as 
-files in the working directory of the Notebook app, also known as the 
+By default, the notebook server stores the notebook documents that it saves as 
+files in the working directory of the notebook server, also known as the
 ``notebook_dir``. This  logic is implemented in the 
 :class:`FileNotebookManager` class. However, the server can be configured to 
 use a different notebook manager class, which can 
@@ -178,9 +155,9 @@ Known issues
 ------------
 
 When behind a proxy, especially if your system or browser is set to autodetect
-the proxy, the Notebook app might fail to connect to the server's websockets,
-and present you with a warning at startup. In this case, you need to configure
-your system not to use the proxy for the server's address.
+the proxy, the notebook web application might fail to connect to the server's
+websockets, and present you with a warning at startup. In this case, you need
+to configure your system not to use the proxy for the server's address.
 
 For example, in Firefox, go to the Preferences panel, Advanced section,
 Network tab, click 'Settings...', and add the address of the notebook server
diff --git a/docs/source/interactive/tutorial.rst b/docs/source/interactive/tutorial.rst
@@ -8,12 +8,27 @@ You don't need to know anything beyond Python to start using IPython – just ty
 commands as you would at the standard Python prompt. But IPython can do much
 more than the standard prompt. Some key features are described here. For more
 information, check the :ref:`tips page <tips>`, or look at examples in the
-`IPython cookbook <http://wiki.ipython.org/index.php?title=Cookbook>`_.
+`IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
 
 If you've never used Python before, you might want to look at `the official
 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
 Python <http://diveintopython.org/toc/index.html>`_.
 
+The four most helpful commands 
+===============================
+
+The four most helpful commands, as well as their brief description, is shown
+to you in a banner, every time you start IPython:
+
+==========    =========================================================
+command       description
+==========    =========================================================
+?             Introduction and overview of IPython's features.
+%quickref     Quick reference.
+help          Python's own help system.
+object?       Details about 'object', use 'object??' for extra details.
+==========    =========================================================
+
 Tab completion
 ==============
 
@@ -31,16 +46,19 @@ including docstrings, function definition lines (for call arguments) and
 constructor details for classes. To get specific information on an object, you
 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
 
+.. _magics_explained:
+
 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
+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.
+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.
 
 The following examples show how to call the builtin ``timeit`` magic, both in
 line and cell mode::
@@ -58,34 +76,41 @@ The builtin magics include:
 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
   ``%recall``, etc.
 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
-  etc.
-- Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
+  ``%automagic``, etc.
+- Other functions such as ``%reset``, ``%timeit``, ``%%file``, ``%load``, or
+  ``%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 (cell magics must always have the
-``%%`` prefix)::
+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::
 
     run thescript.py
 
+You can toggle this behavior by running the ``%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
 read its docstring. To see all the available magic functions, call
 ``%lsmagic``.
 
+.. seealso::
+
+    `Cell magics`_ example notebook
+
 Running and Editing
 -------------------
 
-The %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.
+The ``%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.
 
-%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
+``%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
 profiler (-p).
 
-The %edit command gives a reasonable approximation of multiline editing,
+The ``%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.
 
@@ -153,11 +178,12 @@ visited directories and allows you to go to any previously visited one.
 Configuration
 =============
 
-Much of IPython can be tweaked through configuration. To get started, use the
-command ``ipython profile create`` to produce the default config files. These
-will be placed in :file:`~/.ipython/profile_default` or
-:file:`~/.config/ipython/profile_default`, and contain comments explaining what
-the various options do.
+Much of IPython can be tweaked through :ref:`configuration <config_overview>`.
+To get started, use the command ``ipython profile create`` to produce the
+default config files. These will be placed in
+:file:`~/.ipython/profile_default` or
+:file:`~/.config/ipython/profile_default`, and contain comments explaining
+what the various options do.
 
 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
@@ -173,7 +199,4 @@ as the IPython shell is constructed, before any other code or scripts you have
 specified. The files will be run in order of their names, so you can control the
 ordering with prefixes, like ``10-myimports.py``.
 
-.. note::
-
-    Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
-    in :file:`ipython_config.py` for similar behavior in 0.11.
+.. include:: ../links.txt
diff --git a/docs/source/links.txt b/docs/source/links.txt
@@ -23,6 +23,7 @@
 .. _ipython_github_repo: http://github.com/ipython/ipython/
 .. _ipython_downloads: http://ipython.org/download.html
 .. _ipython_pypi: http://pypi.python.org/pypi/ipython
+.. _nbviewer: http://nbviewer.ipython.org
 
 .. _ZeroMQ: http://zeromq.org
 
@@ -46,7 +47,7 @@
 .. _numpy: http://numpy.scipy.org
 .. _scipy: http://www.scipy.org
 .. _scipy_conference: http://conference.scipy.org
-.. _matplotlib: http://matplotlib.sourceforge.net
+.. _matplotlib: http://matplotlib.org
 .. _pythonxy: http://www.pythonxy.com
 .. _ETS: http://code.enthought.com/projects/tool-suite.php
 .. _EPD: http://www.enthought.com/products/epd.php
@@ -72,4 +73,29 @@
 .. _indefero: http://www.indefero.net
 .. _git: http://git-scm.com
 .. _github: http://github.com
-.. _MarkDown: http://daringfireball.net/projects/markdown/
+.. _Markdown: http://daringfireball.net/projects/markdown/syntax
+
+.. _Running Code in the IPython Notebook: notebook_p1_
+.. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
+
+.. _Basic Output: notebook_p2_
+.. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
+
+.. _Plotting with Matplotlib: notebook_p3_
+.. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
+
+.. _Markdown Cells: notebook_p4
+.. _notebook_p4: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb
+
+.. _Rich Display System: notebook_p5_
+.. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
+
+.. _notebook_custom_display: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Custom%20Display%20Logic.ipynb
+
+.. _Frontend/Kernel Model: notebook_two_proc_
+.. _notebook_two_proc: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Frontend-Kernel%20Model.ipynb
+
+.. _Cell magics: notebook_cell_magics_
+.. _notebook_cell_magics: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Cell%20Magics.ipynb
+
+
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -18,9 +18,9 @@ interactive and exploratory computing.  To support this goal, IPython
 has three main components:
 
 * An enhanced interactive Python shell.
-* A decoupled two-process communication model, which allows for multiple
-  clients to connect to a computation kernel, most notably the web-based
-  :ref:`notebook <htmlnotebook>`
+* A decoupled :ref:`two-process communication model <ipythonzmq>`, which
+  allows for multiple clients to connect to a computation kernel, most notably
+  the web-based :ref:`notebook <htmlnotebook>`
 * An architecture for interactive parallel computing.
 
 All of IPython is open source (released under the revised BSD license).
@@ -197,7 +197,7 @@ 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
+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
@@ -222,6 +222,10 @@ You can read more about using :ref:`ipython qtconsole <qtconsole>`, and
 <messaging>` which documents the protocol for communication between kernels
 and clients.
 
+.. seealso::
+    
+    `Frontend/Kernel Model`_ example notebook
+
 
 Interactive parallel computing
 ==============================
@@ -283,3 +287,4 @@ IPython is known to work on the following operating systems:
 
 See :ref:`here <install_index>` for instructions on how to install IPython.
 
+.. include:: links.txt
