doc/pre-executed.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pre-Executing Notebooks\n",
    "\n",
    "Automatically executing notebooks during the Sphinx build process is an important feature of `nbsphinx`.\n",
    "However, there are a few use cases where pre-executing a notebook and storing the outputs might be preferable.\n",
    "Storing any output will, by default, stop ``nbsphinx`` from executing the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Long-Running Cells\n",
    "\n",
    "If you are doing some very time-consuming computations, it might not be feasible to re-execute the notebook every time you build your Sphinx documentation.\n",
    "\n",
    "So just do it once -- when you happen to have the time -- and then just keep the output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 160 ms, sys: 56 ms, total: 216 ms\n",
      "Wall time: 1h 1s\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "42"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "%time time.sleep(60 * 60)\n",
    "6 * 7"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rare Libraries\n",
    "\n",
    "You might have created results with a library that's hard to install and therefore you have only managed to install it on one very old computer in the basement, so you probably cannot run this whenever you build your Sphinx docs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from a_very_rare_library import calculate_the_answer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "42"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "calculate_the_answer()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exceptions\n",
    "\n",
    "If an exception is raised during the Sphinx build process, it is stopped (the build process, not the exception!).\n",
    "If you want to show to your audience how an exception looks like, you have two choices:\n",
    "\n",
    "1. Allow errors -- either generally or on a per-notebook or per-cell basis -- see [Ignoring Errors](allow-errors.ipynb) ([per cell](allow-errors-per-cell.ipynb)).\n",
    "\n",
    "1. Execute the notebook beforehand and save the results, like it's done in this example notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "ename": "ZeroDivisionError",
     "evalue": "division by zero",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mZeroDivisionError\u001b[0m                         Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-5-b710d87c980c>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0;36m1\u001b[0m \u001b[0;34m/\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mZeroDivisionError\u001b[0m: division by zero"
     ]
    }
   ],
   "source": [
    "1 / 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Client-specific Outputs\n",
    "\n",
    "When `nbsphinx` executes notebooks,\n",
    "it uses the `nbconvert` module to do so.\n",
    "Certain Jupyter clients might produce output\n",
    "that differs from what `nbconvert` would produce.\n",
    "To preserve those original outputs,\n",
    "the notebook has to be executed and saved\n",
    "before running Sphinx.\n",
    "\n",
    "For example,\n",
    "the JupyterLab help system shows the help text as cell outputs,\n",
    "while executing with `nbconvert` doesn't produce any output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;31mSignature:\u001b[0m \u001b[0msorted\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0miterable\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m/\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m*\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mkey\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mNone\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0mreverse\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mFalse\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
       "\u001b[0;31mDocstring:\u001b[0m\n",
       "Return a new list containing all items from the iterable in ascending order.\n",
       "\n",
       "A custom key function can be supplied to customize the sort order, and the\n",
       "reverse flag can be set to request the result in descending order.\n",
       "\u001b[0;31mType:\u001b[0m      builtin_function_or_method\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sorted?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interactive Input\n",
    "\n",
    "If your code asks for user input,\n",
    "it probably doesn't work when executed by Sphinx/`nbsphinx`.\n",
    "You'll probably get an error like this:\n",
    "\n",
    "    StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.\n",
    "\n",
    "In this case, you can run the notebook interactively,\n",
    "provide the desired inputs and then save the notebook including its cell outputs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdin",
     "output_type": "stream",
     "text": [
      "What... is your name? Sir Lancelot of Camelot\n",
      "What... is your quest? To seek the Holy Grail\n",
      "What... is your favorite color? Blue\n"
     ]
    }
   ],
   "source": [
    "name = input('What... is your name?')\n",
    "quest = input('What... is your quest?')\n",
    "color = input('What... is your favorite color?')"
   ]
  }
 ],
 "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.8.6"
  },
  "widgets": {
   "state": {},
   "version": "0.2.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}