DOC: Refactor raw cell docs

spatialaudio · Jan 26, 2016 · 14fbcc4 · 14fbcc4
1 parent 760d7b9
commit 14fbcc4
Show file tree

Hide file tree

Showing 2 changed files with 124 additions and 20 deletions.
diff --git a/doc/images/raw_cells.png b/doc/images/raw_cells.png
diff --git a/doc/raw-cells.ipynb b/doc/raw-cells.ipynb
@@ -6,31 +6,106 @@
    "source": [
     "# Raw Cells\n",
     "\n",
-    "Cells with the cell type \"Raw NBConvert\" can have different formats.\n",
-    "This information is stored in the notebook metadata.\n",
-    "To select the format from within Jupyter, switch the cell toolbar to \"Raw Cell Format\"."
+    "The \"Raw NBConvert\" cell type can be used to render different code formats into HTML or LaTeX by Sphinx.  This information is stored in the notebook metadata and converted appropriately.  To select a desired format from within Jupyter, select the cell containing your special code and choose options from the following dropdown menus:  \n",
+    "\n",
+    "1. Select \"Raw NBConvert\"\n",
+    "2. Switch the Cell Toolbar to \"Raw Cell Format\"\n",
+    "3. Chose the appropriate \"Raw NBConvert Format\" within the cell"
    ]
   },
   {
-   "cell_type": "raw",
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![Steps for converting cells to Raw formats in Jupyter](images/raw_cells.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following examples are different Jupyter cell formats that are rendered by Sphinx."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## None"
+   ]
+  },
+  {
+   "cell_type": "markdown",
    "metadata": {},
    "source": [
     "By default (if no cell format is selected), the cell content is included (without any conversion) in both the HTML and LaTeX output.\n",
     "This is typically not useful at all."
    ]
   },
+  {
+   "cell_type": "raw",
+   "metadata": {},
+   "source": [
+    "\"I'm a None cell\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## reST"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Raw cells in \"reST\" format are interpreted as reStructuredText and parsed by Sphinx. The result is visible in both HTML and LaTeX output. "
+   ]
+  },
   {
    "cell_type": "raw",
    "metadata": {
     "raw_mimetype": "text/restructuredtext"
    },
    "source": [
-    "Raw cells in \"reST\" format are interpreted as reStructuredText_ and parsed by Sphinx_.\n",
-    "The result is visible in both HTML and LaTeX output.\n",
-    "This way, links from Jupyter notebooks to reST pages are possible, e.g. :doc:`rst`.\n",
+    "\"**I'm** a reST_ *cell*.\"\n",
+    "\n",
+    ".. _reST: http://sphinx-doc.org/rest.html"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In addition, a raw cell formatted in reST can link to normal .rst files using \n",
     "\n",
-    ".. _reStructuredText: http://sphinx-doc.org/rest.html\n",
-    ".. _Sphinx: http://sphinx-doc.org/"
+    "    :doc:`rst_filename`  \n",
+    "\n",
+    "The latter code will render as a link to the appropriate .rst file.  See the following link for more information on linking between files."
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
+   "source": [
+    "\"I'm a notebook cell with a link to a .rst file called :doc:`rst`.\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Markdown"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Raw cells in \"Markdown\" format are interpreted as Markdown, and the result is included in both HTML and LaTeX output.  Since the Jupyter Notebook also supports normal Markdown cells, this might not be useful *at all*."
    ]
   },
   {
@@ -39,8 +114,21 @@
     "raw_mimetype": "text/markdown"
    },
    "source": [
-    "Raw cells in \"Markdown\" format are interpreted as [Markdown](https://daringfireball.net/projects/markdown/) and the result is included in both HTML and LaTeX output.\n",
-    "Since the Jupyter Notebook also supports \"normal\" Markdown cells, this might not be useful *at all*."
+    "\"**I'm** a [Markdown](https://daringfireball.net/projects/markdown/) *cell*.\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## HTML"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Raw cells in \"HTML\" format are only visible in HTML output. This option might not be very useful, since raw HTML code is also allowed within normal Markdown cells."
    ]
   },
   {
@@ -49,9 +137,21 @@
     "raw_mimetype": "text/html"
    },
    "source": [
-    "<p>Raw cells in &ldquo;HTML&rdquo; format are only included in HTML output (without any conversion).\n",
-    "This might not be <em>very useful</em>, since raw HTML code is also allowed within &ldquo;normal&rdquo; Markdown cells.</p>\n",
-    "<p>Raw cells in &ldquo;LaTeX&rdquo; format are only included in LaTeX output.</p>"
+    "<p>&ldquo;<b>I&rsquo;m</b> an <a href=\"http://www.w3schools.com/tags/default.asp\">HTML</a> <em>cell</em>.&rdquo;</p>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Latex"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Raw cells in \"LaTeX\" format are only visible in LaTeX output."
    ]
   },
   {
@@ -60,17 +160,21 @@
     "raw_mimetype": "text/latex"
    },
    "source": [
-    "Raw cells in ``LaTeX'' format are only included in \\LaTeX\\ output (without any conversion).\n",
-    "\n",
-    "Raw cells in ``HTML'' format are only included in HTML output.\n",
-    "This might not be \\emph{very useful}, since raw HTML code is also allowed within ``normal'' Markdown cells."
+    "\\textbf{I'm} a \\href{https://www.latex-project.org/}{\\LaTeX} \\textit{cell}."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Python"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Raw cells in \"Python\" format are not shown at all (nor acted upon in any way)."
+    "Raw cells in \"Python\" format are not visible at all (nor executed in any way)."
    ]
   },
   {
@@ -100,7 +204,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.4.4"
+   "version": "3.3.5"
   }
  },
  "nbformat": 4,