docs/use/notebooks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Content with Jupyter Notebooks\n",
    "\n",
    "You can create content with Jupyter Notebooks. For example, the content for the current page is contained\n",
    "in {download}`this notebook file <./notebooks.ipynb>`. \n",
    "\n",
    "Jupyter Book supports all markdown that is supported by Jupyter Notebooks.\n",
    "This is mostly a of markdown called\n",
    "[CommonMark Markdown](https://commonmark.org/). It has many elements\n",
    "for standard text processing, though it lacks a lot of features used for\n",
    "publishing and documentation. If you need these extra features in Jupyter\n",
    "Book, see {doc}`myst`.\n",
    "\n",
    "This page describes some basic features of Jupyter Notebook markdown, and how to\n",
    "include them with your book.\n",
    "\n",
    "```{sidebar} You can also write content in markdown files.\n",
    "In fact, Jupyter Book supports a\n",
    "fancier version of markdown than what Jupyter Notebooks support by default. For more\n",
    "information about this, check out {doc}`myst`.\n",
    "```\n",
    "\n",
    "## Embedding media\n",
    "\n",
    "### Adding images\n",
    "\n",
    "You can reference external media like images from your markdown file. If you use\n",
    "relative paths, then they will continue to work when the markdown files are copied over,\n",
    "so long as they point to a file that's inside of the repository.\n",
    "\n",
    "Here's an image relative to the book content root\n",
    "\n",
    "![](../images/C-3PO_droid.png)\n",
    "\n",
    "It was generated with this code:\n",
    "\n",
    "```\n",
    "![](../images/C-3PO_droid.png)\n",
    "```\n",
    "\n",
    "### Adding movies\n",
    "\n",
    "You can even embed references to movies on the web! For example, here's a little gif for you!\n",
    "\n",
    "![](https://media.giphy.com/media/yoJC2A59OCZHs1LXvW/giphy.gif)\n",
    "\n",
    "This will be included in your book when it is built.\n",
    "\n",
    "\n",
    "\n",
    "## Mathematics\n",
    "\n",
    "Jupyter Book uses the excellent [MathJax](http://docs.mathjax.org/en/latest/) library,\n",
    "along with the default Jupyter Notebook configuration, for rendering mathematics from\n",
    "latex-style syntax.\n",
    "\n",
    "For example, here's a mathematical expression rendered with MathJax:\n",
    "\n",
    "$$\n",
    "P(A_1 \\cup A_2 \\cup A_3) ~ = ~ P(B \\cup A_3) &= ~ P(B) + P(A_3) - P(BA_3) \\\\\n",
    "&= ~ P(A_1) + P(A_2) - P(A_1A_2) + P(A_3) - P(A_1A_3 \\cup A_2A_3)\\\\\n",
    "&= ~ \\sum_{i=1}^3 P(A_i) - \\mathop{\\sum \\sum}_{1 \\le i < j \\le 3} P(A_iA_j) + P(A_1A_2A_3)\n",
    "$$\n",
    "\n",
    "### Block-level math\n",
    "\n",
    "You can include block-level math by wrapping your math in `$$` characters.\n",
    "For example, the following block:\n",
    "\n",
    "```\n",
    "$$\n",
    "wow = its^{math}\n",
    "$$\n",
    "```\n",
    "\n",
    "Results in this output:\n",
    "\n",
    "$$\n",
    "wow = its^{math}\n",
    "$$\n",
    "\n",
    "You can also include math blocks by using latex-style syntax using\n",
    "`\\begin{align*}`. For example, the following block:\n",
    "\n",
    "```\n",
    "\\begin{align*}\n",
    "yep = its_more^math\n",
    "\\end{align*}\n",
    "```\n",
    "\n",
    "Results in:\n",
    "\n",
    "\\begin{align*}\n",
    "yep = its_more^math\n",
    "\\end{align*}\n",
    "\n",
    "For more information about math with Jupyter Book, see {doc}`math`.\n",
    "\n",
    "## Code blocks and image outputs\n",
    "\n",
    "Jupyter Book will also embed your code blocks and output in your book.\n",
    "For example, here's some sample Matplotlib code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from matplotlib import rcParams, cycler\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "plt.ion()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Fixing random state for reproducibility\n",
    "np.random.seed(19680801)\n",
    "\n",
    "N = 10\n",
    "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n",
    "data = np.array(data).T\n",
    "cmap = plt.cm.coolwarm\n",
    "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n",
    "\n",
    "\n",
    "from matplotlib.lines import Line2D\n",
    "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n",
    "                Line2D([0], [0], color=cmap(.5), lw=4),\n",
    "                Line2D([0], [0], color=cmap(1.), lw=4)]\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(10, 5))\n",
    "lines = ax.plot(data)\n",
    "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the image above is captured and displayed in your site."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "popout",
     "remove-input"
    ]
   },
   "outputs": [],
   "source": [
    "# Fixing random state for reproducibility\n",
    "np.random.seed(19680801)\n",
    "\n",
    "N = 10\n",
    "data = [np.logspace(0, 1, 100) + .1*np.random.randn(100) + ii for ii in range(N)]\n",
    "data = np.array(data).T\n",
    "cmap = plt.cm.coolwarm\n",
    "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n",
    "\n",
    "\n",
    "from matplotlib.lines import Line2D\n",
    "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n",
    "                Line2D([0], [0], color=cmap(.5), lw=4),\n",
    "                Line2D([0], [0], color=cmap(1.), lw=4)]\n",
    "\n",
    "fig, ax = plt.subplots(figsize=(10, 5))\n",
    "lines = ax.plot(data)\n",
    "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'])\n",
    "ax.set(title=\"Smoother linez\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": [
     "popout"
    ]
   },
   "source": [
    "```{sidebar} **You can also pop out content to the side!**\n",
    "For more information on how to do this,\n",
    "check out the {ref}`layout/sidebar` section.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Removing content before publishing\n",
    "\n",
    "You can also remove some content before publishing your book to the web. For example,\n",
    "in [the original notebook](https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/content/use/notebooks.ipynb) there\n",
    "used to be a cell below..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-cell"
    ]
   },
   "outputs": [],
   "source": [
    "thisvariable = \"none of this should show up in the textbook\"\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "x = np.random.randn(100)\n",
    "y = np.random.randn(100)\n",
    "ax.scatter(x, y, s=np.abs(x*100), c=x, cmap=plt.cm.coolwarm)\n",
    "ax.text(0, .5, thisvariable, fontsize=20, transform=ax.transAxes)\n",
    "ax.set_axis_off()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also **remove only the code** so that images and other output still show up.\n",
    "\n",
    "Below we'll *only* display an image. It was generated with Python code in a cell,\n",
    "which you can [see in the original notebook](https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/book_template/content/use/notebooks.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "thisvariable = \"this plot *will* show up in the textbook.\"\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "x = np.random.randn(100)\n",
    "y = np.random.randn(100)\n",
    "ax.scatter(x, y, s=np.abs(x*100), c=x, cmap=plt.cm.coolwarm)\n",
    "ax.text(0, .5, thisvariable, fontsize=20, transform=ax.transAxes)\n",
    "ax.set_axis_off()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And here we'll *only* display a Pandas DataFrame. Again, this was generated with Python code\n",
    "from [this original notebook](https://github.com/jupyter/textbooks-with-jupyter/blob/master/notebooks/introduction/notebooks.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide-input"
    ]
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "pd.DataFrame([['hi', 'there'], ['this', 'is'], ['a', 'DataFrame']], columns=['Word A', 'Word B'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interactive outputs\n",
    "\n",
    "We can even do the same for *interactive* material. Below we'll display a map using [folium](https://python-visualization.github.io/folium/). When the notebook\n",
    "is converted to Markdown, the code for creating the interactive map is retained.\n",
    "\n",
    "**Note that this will only work for some packages.** They need to be able to output standalone HTML/Javascript, and not\n",
    "depend on an underlying Python kernel to work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import folium"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "m = folium.Map(\n",
    "    location=[45.372, -121.6972],\n",
    "    zoom_start=12,\n",
    "    tiles='Stamen Terrain'\n",
    ")\n",
    "\n",
    "folium.Marker(\n",
    "    location=[45.3288, -121.6625],\n",
    "    popup='Mt. Hood Meadows',\n",
    "    icon=folium.Icon(icon='cloud')\n",
    ").add_to(m)\n",
    "\n",
    "folium.Marker(\n",
    "    location=[45.3311, -121.7113],\n",
    "    popup='Timberline Lodge',\n",
    "    icon=folium.Icon(color='green')\n",
    ").add_to(m)\n",
    "\n",
    "folium.Marker(\n",
    "    location=[45.3300, -121.6823],\n",
    "    popup='Some Other Location',\n",
    "    icon=folium.Icon(color='red', icon='info-sign')\n",
    ").add_to(m)\n",
    "\n",
    "\n",
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rich outputs from notebook cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because notebooks have rich text outputs, you can store these in\n",
    "your Jupyter Book as well!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!jupyter-book build --help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [],
   "source": [
    "this_will_error"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing markdown with more features\n",
    "\n",
    "In addition to CommonMark markdown, Jupyter Book also supports a more\n",
    "fully-featured version of markdown called **MyST Markdown**. This is a slight\n",
    "addition to CommonMark that includes syntactic pieces that are useful for\n",
    "publishing computational narratives. For more information about MyST\n",
    "Markdown, see {doc}`myst`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}