Merge pull request #159 from jdfreder/docs

Move examples into docs folder, and integrate with docs.

docs/Makefile

@@ -19,7 +19,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext ipynb2rst
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -52,7 +52,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/config.rst
 
-html: source/config.rst
+html: source/config.rst ipynb2rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -61,6 +61,10 @@ source/config.rst:
 	python3 autogen_config.py
 	@echo "Created docs for config options"
 
+ipynb2rst:
+	jupyter nbconvert --to rst source/examples/Notebook/*.ipynb --template=source/template --FilesWriter.build_directory=source/examples/Notebook
+	@echo "Converted notebooks to rst"
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/source/examples/Notebook/Configuring the Notebook and Server.rst

@@ -0,0 +1,188 @@
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Configuring%20the%20Notebook%20and%20Server.ipynb>`__
+
+Configuring the Notebook and Server
+===================================
+
+Configuring the Jupyter Notebook
+--------------------------------
+
+The notebook web server can also be configured using Jupyter profiles
+and configuration files. The Notebook web server configuration options
+are set in a file named ``jupyter_notebook_config.py`` in your Jupyter
+directory, which itself is usually ``.jupyter`` in your home directory.
+
+The default version of ``jupyter_notebook_config.py`` lists all of the
+options available along with documentation for each. Changes made to
+that file will affect all notebook servers run under that profile.
+Command line options always override those set in configuration files.
+
+You can create a new config:
+
+.. code:: python
+
+    !jupyter notebook --generate-config
+
+More details about Jupyter configuration files and profiles can be found
+`here <http://ipython.org/ipython-doc/dev/config/intro.html>`__.
+
+Securing the notebook server
+----------------------------
+
+The Jupyter Notebook allows arbitrary code execution on the computer
+running it. Thus, the notebook web server should never be run on the
+open internet without first securing it. By default, the notebook server
+only listens on local network interface (``127.0.0.1``) There are two
+steps required to secure the notebook server:
+
+1. Setting a password
+2. Encrypt network traffic using SSL
+
+Setting a password
+~~~~~~~~~~~~~~~~~~
+
+You can protect your notebook server with a simple single password by
+setting the ``NotebookApp.password`` configurable. You can prepare a
+hashed password using the function ``IPython.lib.passwd``:
+
+.. code:: python
+
+    from IPython.lib import passwd
+    password = passwd("secret")
+    password
+
+You can then add this to your ``jupyter_notebook_config.py``:
+
+.. code:: python
+
+    # Password to use for web authentication
+    c = get_config()
+    c.NotebookApp.password = 
+    u'sha1:6c2164fc2b22:ed55ecf07fc0f985ab46561483c0e888e8964ae6'
+
+Using SSL/HTTPS
+~~~~~~~~~~~~~~~
+
+When using a password, it is a good idea to also use SSL, so that your
+password is not sent unencrypted by your browser to the web server. When
+running the notebook on the public internet this is absolutely required.
+
+The first step is to generate an SSL certificate. A self-signed
+certificate can be generated with ``openssl``. For example, the
+following command will create a certificate valid for 365 days with both
+the key and certificate data written to the same file:
+
+::
+
+    openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
+
+In most cases, you should run this command in your profile directory,
+which will make it easy to use the generated key and certificate.
+
+When you connect to a notebook server over HTTPS using a self-signed
+certificate, your browser will warn you of a dangerous certificate
+because it is 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>`__
+
+When you enable SSL support, you will need to access the notebook server
+over ``https://``, rather than plain ``http://``. The startup message
+from the notebook server prints the correct URL, but it is easy to
+overlook and think the server is for some reason non-responsive.
+
+Once you have generated the key and certificate, you can configure the
+notebook server to use them, by adding the following to
+``jupyter_notebook_config.py``:
+
+.. code:: python
+
+    # The full path to an SSL/TLS certificate file.
+    c.NotebookApp.certfile = u'/Users/bgranger/.jupyter/mycert.crt'
+
+    # The full path to a private key file for usage with SSL/TLS.
+    c.NotebookApp.keyfile = u'/Users/bgranger/.jupyter/mycert.key'
+
+Running a public notebook server
+--------------------------------
+
+.. raw:: html
+
+   <div class="alert alert-error">
+
+Don't run a public notebook server unless you first secure it with a
+password and SSL/HTTPS as described above
+
+.. raw:: html
+
+   </div>
+
+By default the notebook server only listens on the
+``localhost/127.0.0.1`` network interface. If you want to connect to the
+notebook from another computers, or over the internet, you need to
+configure the notebook server to listen on all network interfaces and
+not open the browser. You will often also want to disable the automatic
+launching of the web browser.
+
+This can be accomplished by passing a command line options.
+
+::
+
+    jupyter notebook --ip=* --no-browser
+
+You can also add the following to your ``jupyter_notebook_config.py``
+file:
+
+.. code:: python
+
+    c.NotebookApp.ip = '*'
+    c.NotebookApp.open_browser = False
+
+Running with a different URL prefix
+-----------------------------------
+
+The notebook dashboard typically lives at the URL
+``http://localhost:8888/tree``. If you prefer that it lives, together
+with the rest of the notebook web application, under a base URL prefix,
+such as ``http://localhost:8888/ipython/tree``, you can do so by adding
+the following lines to your ``jupyter_notebook_config.py`` file.
+
+.. code:: python
+
+    c.NotebookApp.base_url = '/ipython/'
+    c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
+
+Using a different notebook store
+--------------------------------
+
+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
+``FileNotebookManager`` class. However, the server can be configured to
+use a different notebook manager class, which can store the notebooks in
+a different format.
+
+The `bookstore <https://github.com/rgbkrk/bookstore>`__ package
+currently allows users to store notebooks on Rackspace CloudFiles or
+OpenStack Swift based object stores.
+
+Writing a notebook manager is as simple as extending the base class
+``NotebookManager``. The
+`simple\_notebook\_manager <https://github.com/khinsen/simple_notebook_manager>`__
+provides a great example of an in memory notebook manager, created
+solely for the purpose of illustrating the notebook manager API.
+
+Known issues
+------------
+
+When behind a proxy, especially if your system or browser is set to
+autodetect 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 to the 'No proxy for' field.
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Configuring%20the%20Notebook%20and%20Server.ipynb>`__

docs/source/examples/Notebook/Connecting with the Qt Console.rst

@@ -0,0 +1,67 @@
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Connecting%20with%20the%20Qt%20Console.ipynb>`__
+
+Connecting to an existing IPython kernel using the Qt Console
+=============================================================
+
+The Frontend/Kernel Model
+-------------------------
+
+The traditional IPython (``ipython``) consists of a single process that
+combines a terminal based UI with the process that runs the users code.
+
+While this traditional application still exists, the modern Jupyter
+consists of two processes:
+
+-  Kernel: this is the process that runs the users code.
+-  Frontend: this is the process that provides the user interface where
+   the user types code and sees results.
+
+Jupyter currently has 3 frontends:
+
+-  Terminal Console (``ipython console``)
+-  Qt Console (``ipython qtconsole``)
+-  Notebook (``ipython notebook``)
+
+The Kernel and Frontend communicate over a ZeroMQ/JSON based messaging
+protocol, which allows multiple Frontends (even of different types) to
+communicate with a single Kernel. This opens the door for all sorts of
+interesting things, such as connecting a Console or Qt Console to a
+Notebook's Kernel. For example, you may want to connect a Qt console to
+your Notebook's Kernel and use it as a help browser, calling ``??`` on
+objects in the Qt console (whose pager is more flexible than the one in
+the notebook).
+
+This Notebook describes how you would connect another Frontend to a
+Kernel that is associated with a Notebook.
+
+Manual connection
+-----------------
+
+To connect another Frontend to a Kernel manually, you first need to find
+out the connection information for the Kernel using the
+``%connect_info`` magic:
+
+.. code:: python
+
+    %connect_info
+
+You can see that this magic displays everything you need to connect to
+this Notebook's Kernel.
+
+Automatic connection using a new Qt Console
+-------------------------------------------
+
+You can also start a new Qt Console connected to your current Kernel by
+using the ``%qtconsole`` magic. This will detect the necessary
+connection information and start the Qt Console for you automatically.
+
+.. code:: python
+
+    a = 10
+
+.. code:: python
+
+    %qtconsole
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Connecting%20with%20the%20Qt%20Console.ipynb>`__

docs/source/examples/Notebook/Custom Keyboard Shortcuts.rst

@@ -0,0 +1,71 @@
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Custom%20Keyboard%20Shortcuts.ipynb>`__
+
+Keyboard Shortcut Customization
+===============================
+
+Starting with IPython 2.0 keyboard shortcuts in command and edit mode
+are fully customizable. These customizations are made using the Jupyter
+JavaScript API. Here is an example that makes the ``r`` key available
+for running a cell:
+
+.. code:: python
+
+    %%javascript
+    
+    Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', {
+        help : 'run cell',
+        help_index : 'zz',
+        handler : function (event) {
+            IPython.notebook.execute_cell();
+            return false;
+        }}
+    );
+
+"By default the keypress ``r``, while in command mode, changes the type
+of the selected cell to ``raw``. This shortcut is overridden by the code
+in the previous cell, and thus the action no longer be available via the
+keypress ``r``."
+
+There are a couple of points to mention about this API:
+
+-  The ``help_index`` field is used to sort the shortcuts in the
+   Keyboard Shortcuts help dialog. It defaults to ``zz``.
+-  When a handler returns ``false`` it indicates that the event should
+   stop propagating and the default action should not be performed. For
+   further details about the ``event`` object or event handling, see the
+   jQuery docs.
+-  If you don't need a ``help`` or ``help_index`` field, you can simply
+   pass a function as the second argument to ``add_shortcut``.
+
+.. code:: python
+
+    %%javascript
+    
+    Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {
+        IPython.notebook.execute_cell();
+        return false;
+    });
+
+Likewise, to remove a shortcut, use ``remove_shortcut``:
+
+.. code:: python
+
+    %%javascript
+    
+    Jupyter.keyboard_manager.command_shortcuts.remove_shortcut('r');
+
+If you want your keyboard shortcuts to be active for all of your
+notebooks, put the above API calls into your ``custom.js`` file.
+
+Of course we provide name for majority of existing action so that you do
+not have to re-write everything, here is for example how to bind ``r``
+back to it's initial behavior:
+
+.. code:: python
+
+    %%javascript
+    
+    Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'ipython.change-selected-cell-to-raw-cell');
+
+`View the original notebook on nbviewer <http://nbviewer.jupyter.org/github/ipython/ipython/blob/master/docs/source/examples/Notebook/Custom%20Keyboard%20Shortcuts.ipynb>`__

examples/Notebook/Index.ipynb → docs/source/examples/Notebook/Examples and Tutorials Index.ipynb

@@ -11,14 +11,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Notebook"
+    "# Examples and Tutorials"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The Jupyter Notebook is a web-based interactive computing system that enables users to author documents that include live code, narrative text, LaTeX equations, HTML, images and video. These documents contain a full record of a computation and its results and can be shared on email, [Dropbox](http://dropbox.com), version control systems (like git/[GitHub](http://github.com)) or [nbviewer.jupyter.org](http://nbviewer.jupyter.org)."
+    "This portion of the documentation was generated from notebook files.  You can download the original interactive notebook files using the links at the tops and bottoms of the pages."
    ]
   },
   {