{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Executing pages of your book\n",
    "\n",
    "✨**experimental**✨\n",
    "\n",
    "Sometimes you'd like to execute each page's content before building its HTML - this\n",
    "ensures that the outputs are up-to-date and that they still run. Jupyter Book\n",
    "has the ability to execute any code in your content when you build each page's HTML although by default this is disabled for notebook and simple markdown documents.\n",
    "\n",
    "## Default execution behavior\n",
    "\n",
    "Jupyter Book will decide whether to execute your book's content based on the types of files used to store your content. By default, Jupyter Book assumes that :\n",
    "\n",
    "-  notebook outputs are already present in an `.ipynb` file, and consequently any __Jupyter Notebooks__ (`.ipynb` documents), will __not be executed__; (see below for how to change this behavior);\n",
    "- __simple raw markdown files__ (`.md`, no Jupytext header) will also __not be executed__: Jupyter Book assumes that any code blocks were meant for viewing only, not running;\n",
    "- any __Jupytext documents__ (currently, `.py`, `.md`, or `.Rmd` files that have jupytext YAML front-matter content) __will be executed__ when the page's HTML is built.\n",
    "\n",
    "There are a few ways to alter this behavior in order to **execute your book content at build time** using several convenience functions and options which we'll cover below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run a single page in-place: **`jupyter-book run`**\n",
    "\n",
    "Jupyter Book provides a convenience command-line function that executes\n",
    "one or more Jupyter Notebooks and stores the outputs inline within the same `ipynb` file. This provides a straightforward way of ensuring that source notebook files contain freshly computed cell outputs when you create your Jupyter Book.\n",
    "\n",
    "This `jupyter-book run` command-line function can be called with the path to a single\n",
    "book page like so:\n",
    "\n",
    "```\n",
    "jupyter-book run path/to/notebook.ipynb\n",
    "```\n",
    "\n",
    "It will simply execute the notebook and insert the code cell outputs in-place.\n",
    "\n",
    "You can also specify a folder with a **collection** of pages as the first argument:\n",
    "\n",
    "```\n",
    "jupyter-book run path/to/notebook_folder\n",
    "```\n",
    "\n",
    "In this case, all notebooks in this folder and sub-folders will be run in-place."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run all your book's content when building: **`jupyter-book build --execute`**\n",
    "\n",
    "If you'd like to run each page of your book (where possible) when building the\n",
    "HTML for your book pages *without* modifying the original source document, use the `--execute` flag when building each page's HTML:\n",
    "\n",
    "`jupyter-book build --execute`\n",
    "\n",
    "This will cause each `.ipynb` and jupytext-formatted page to be **executed** when it is built.\n",
    "In this case, the source content files will __not__ be modified, but the code execution outputs will be placed in each page's HTML.\n",
    "\n",
    "Remember that the HTML for each page is cached until you update your content. The\n",
    "first time you run `jupyter-book build --execute`, each page of your book will be run\n",
    "and converted to HTML which may take some time. However, after the first run, only the pages that have been updated will be executed and converted to HTML, which should lead to subsequently faster build times as you update your content.\n",
    "\n",
    "Here's a quick summary of this behavior:\n",
    "\n",
    "| Type | `jupyter run` |  `jupyter-book build ` | `jupyter-book build --execute`|\n",
    "|---|---|---|---|\n",
    "| Jupyter Notebooks (`.ipynb`) | Code executes; fresh outputs inserted inline in source notebook | Code doesn't execute; outstanding outputs displayed inline in HTML | Code executes; fresh outputs displayed inline in HTML  |\n",
    "| Raw markdown (`.md`) | Code doesn't execute | Code doesn't execute; generated code outputs not supported in raw markdown documents |  Code doesn't execute; generated code outputs not available for HTML |\n",
    "| Jupytext pages (`.md`, `.Rmd`, `.py`) | Code outputs not supported in Jupytext documents | Code executes; fresh outputs displayed inline in HTML  | Code executes; fresh outputs displayed inline in HTML |"
   ]
  }
 ],
 "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.7.3"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}