Move index.rst content to index.ipynb

This reduces the duplication previously mentioned in the notebook.
It also demonstrates the bi-directional communication between
Jupyter notebooks and Sphinx achieved through the Notebook directive.

doc/index.ipynb

@@ -4,22 +4,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# An Alternative Index Page\n",
-    "\n",
-    "The main index is in [index.rst](index.rst), from which the HTML and LaTeX index is created.\n",
-    "See also the [online version](http://nbsphinx.readthedocs.org/).\n",
-    "\n",
-    "You can use this page as a fallback for when the notebooks are opened locally with Jupyter or online at [nbviewer](http://nbviewer.jupyter.org/github/spatialaudio/nbsphinx/blob/master/doc/index.ipynb)."
+    "All content shown below -- except for the section [A Normal reStructuredText File](rst.rst) -- was\n",
+    "generated from Jupyter notebooks."
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "nbsphinx-toctree": {
+     "maxdepth": 3
+    }
+   },
    "source": [
-    "## Table Of Contents\n",
-    "\n",
-    "These contents are **not** automatically synchronized with `index.rst`, therefore one or the other will likely be out-of-date!\n",
-    "\n",
     "* [Usage](usage.ipynb)\n",
     "* [Markdown Cells](markdown-cells.ipynb)\n",
     "* [Code Cells](code-cells.ipynb)\n",
@@ -30,13 +26,24 @@
     "* [Hidden Cells](hidden-cells.ipynb)\n",
     "* [A Notebook in a Sub-Directory](subdir/another.ipynb)\n",
     "* [Using `toctree` In A Notebook](subdir/toctree.ipynb)\n",
-    "* [External Links](links.ipynb)\n",
+    "* [A Normal reStructuredText file](rst.rst)\n",
+    "* [External Links](links.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
+   "source": [
+    ".. only:: html\n",
     "\n",
-    "... and there is an [Orphan Notebook](orphan.ipynb), which contains a link back to this page (or back to the main index in case of the Sphinx-generated files)."
+    "    There is also :ref:`orphan.ipynb`, just for the sake of it."
    ]
   }
  ],
  "metadata": {
+  "celltoolbar": "Raw Cell Format",
   "kernelspec": {
    "display_name": "Python 3",
    "language": "python",

doc/index.rst

@@ -1,24 +1,3 @@
 .. include:: ../README.rst
 
-All content shown below -- except for the section :doc:`rst` -- was
-generated from Jupyter notebooks.
-
-.. toctree::
-    :maxdepth: 3
-    :glob:
-
-    usage.ipynb
-    markdown-cells.ipynb
-    code-cells.ipynb
-    raw-cells.ipynb
-    pre-executed.ipynb
-    allow-errors.ipynb
-    timeout.ipynb
-    hidden-cells.ipynb
-    subdir/*
-    rst.rst
-    links.ipynb
-
-.. only:: html
-
-    There is also :ref:`orphan.ipynb`, just for the sake of it.
+.. notebook:: index.ipynb