Add example using the nbinclude directive

The added notebook is included in the `rst.rst` document, but not
added to any toctrees.

doc/rst.rst

@@ -36,6 +36,26 @@ These links were created with:
     * "``../``" is not allowed, you have to specify the full path even if the
       current source file is in a subdirectory!
 
+Sphinx Directive for Including Notebooks
+----------------------------------------
+
+Notebooks can also be included directly in an RST file
+using the ``nbinclude`` directive.
+Below, we include :ref:`subdir2/included.ipynb`.
+
+.. nbinclude:: subdir2/included.ipynb
+
+The notebook was included with:
+
+.. code-block:: rst
+
+    .. nbinclude:: subdir2/included.ipynb
+
+.. note::
+
+    * "``../``" is allowed here. In fact, you can include notebooks that are
+      outside of the documentation directory!
+
 Sphinx Directives for Jupyter Notebook Cells
 --------------------------------------------
 

doc/subdir2/included.ipynb

@@ -0,0 +1,59 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "source": [
+    "This notebook is part of the `nbsphinx` documentation: http://nbsphinx.readthedocs.org/."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### An Included Notebook\n",
+    "\n",
+    "This notebook is included with the `nbinclude` directive.\n",
+    "\n",
+    "The cell below is stored unexecuted, but will be executed when included, just like notebooks included in a `:toctree:`. Notebooks with at least one executed cell will not be executed when included."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "6 * 7"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.5.1+"
+  },
+  "nbsphinx": {
+   "orphan": true
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}