DOC: Add information about removing output cells for Git

Some of this is taken from #118.

Author: mgeier

doc/pre-executed.ipynb

@@ -16,7 +16,8 @@
     "# 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."
+    "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."
    ]
   },
   {

doc/usage.ipynb

@@ -78,6 +78,15 @@
     "Subsequent builds will be faster, because only those source files which have changed will be re-built.\n",
     "To force re-building all source files, use the `-E` option.\n",
     "\n",
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "**Note:**\n",
+    "\n",
+    "By default, notebooks will be executed during the Sphinx build process only if they do not have any output cells stored.\n",
+    "See [Controlling Notebook Execution](executing-notebooks.ipynb).\n",
+    "\n",
+    "</div>\n",
+    "\n",
     "To create LaTeX output, use:\n",
     "\n",
     "    python3 -m sphinx <source-dir> <build-dir> -b latex\n",
@@ -318,6 +327,38 @@
     "\n",
     "If you know of another Sphinx theme that should be included here, please open an [issue on Github](https://github.com/spatialaudio/nbsphinx/issues)."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using Notebooks with Git\n",
+    "\n",
+    "[Git](https://git-scm.com/) is extremely useful for managing source code and it can and should also be used for managing Jupyter notebooks.\n",
+    "There is one caveat, however:\n",
+    "Notebooks can contain output cells with rich media like images, plots, sounds, HTML, JavaScript and many other types of bulky machine-created content.\n",
+    "This can make it hard to work with Git efficiently, because changes in those bulky contents can completely obscure the more interesting changes in text and source code.\n",
+    "Working with multiple collaborators on a notebook can become very tedious because of this.\n",
+    "\n",
+    "It is therefore highly recommended that you remove all outputs from your notebooks before committing changes to a Git repository (except for the reasons mentioned in [Pre-Executing Notebooks](pre-executed.ipynb)).\n",
+    "\n",
+    "If there are no output cells in a notebook, `nbsphinx` will by default execute the notebook and the pages generated by Sphinx will therefore contain all the output cells.\n",
+    "See [Controlling Notebook Execution](executing-notebooks.ipynb) for how this behavior can be customized.\n",
+    "\n",
+    "In the Jupyter Notebook application, you can manually clear all outputs by selecting\n",
+    "\"Cell\" $\\to$ \"All Output\" $\\to$ \"Clear\" from the menu.\n",
+    "\n",
+    "There are several tools available to remove outputs from multiple files at once without having to open them separately.\n",
+    "You can even include such a tool as \"clean/smudge filters\" into your Git workflow, which will strip the output cells automatically whenever a Git command is executed.\n",
+    "For details, have a look at those links:\n",
+    "\n",
+    "* https://github.com/kynan/nbstripout\n",
+    "* https://github.com/toobaz/ipynb_output_filter\n",
+    "* http://tillahoffmann.github.io/2017/04/17/versioning-jupyter-notebooks-with-git.html\n",
+    "* http://timstaley.co.uk/posts/making-git-and-jupyter-notebooks-play-nice/\n",
+    "* http://pascalbugnion.net/blog/ipython-notebooks-and-git.html\n",
+    "\n"
+   ]
   }
  ],
  "metadata": {