Notebooks guide (#3781)

Adds guidance on styling and development of notebooks.

CONTRIBUTING.md

@@ -118,3 +118,7 @@ annotations like `# type: ignore`.
 
 For larger contributions that will benefit from design reviews, please use the 
 [Request for Comment](docs/dev/rfc_process.md) process.
+
+## Developing notebooks 
+
+Please refer to our [notebooks guide](docs/dev/notebooks.md) on how to develop iPython notebooks for documentation.

docs/_book.yaml

@@ -76,6 +76,8 @@ upper_tabs:
         path: /cirq/dev/rfc_process
       - title: "Style guide"
         path: /cirq/dev/style
+      - title: "Notebooks guide"
+        path: /cirq/dev/notebooks
       - title: "Nomenclature"
         path: /cirq/dev/nomenclature
       - title: "Gate and operation guidelines"

docs/_template.ipynb

@@ -0,0 +1,94 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "SzKwuqYESWwm"
+   },
+   "source": [
+    "##### Copyright 2021 The Cirq Developers"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form",
+    "id": "4yPUsdJxSXFq"
+   },
+   "outputs": [],
+   "source": [
+    "#@title Licensed under the Apache License, Version 2.0 (the \"License\");\n",
+    "# you may not use this file except in compliance with the License.\n",
+    "# You may obtain a copy of the License at\n",
+    "#\n",
+    "# https://www.apache.org/licenses/LICENSE-2.0\n",
+    "#\n",
+    "# Unless required by applicable law or agreed to in writing, software\n",
+    "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
+    "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
+    "# See the License for the specific language governing permissions and\n",
+    "# limitations under the License."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "dVkNQc0WSIwk"
+   },
+   "source": [
+    "# $$$REPLACE_WITH_TITLE$$$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "zC1qlUJoSXhm"
+   },
+   "source": [
+    "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
+    "  <td>\n",
+    "    <a target=\"_blank\" href=\"https://quantumai.google/cirq/$$$REPLACE_WITH_SITE_URL$$$>\"><img src=\"https://quantumai.google/site-assets/images/buttons/quantumai_logo_1x.png\" />View on QuantumAI</a>\n",
+    "  </td>\n",
+    "  <td>\n",
+    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/quantumlib/Cirq/blob/master/docs/$$$REPLACE_WITH_NOTEBOOK_PATH$$$\"><img src=\"https://quantumai.google/site-assets/images/buttons/colab_logo_1x.png\" />Run in Google Colab</a>\n",
+    "  </td>\n",
+    "  <td>\n",
+    "    <a target=\"_blank\" href=\"https://github.com/quantumlib/Cirq/blob/master/docs/$$$REPLACE_WITH_NOTEBOOK_PATH$$$\"><img src=\"https://quantumai.google/site-assets/images/buttons/github_logo_1x.png\" />View source on GitHub</a>\n",
+    "  </td>\n",
+    "  <td>\n",
+    "    <a href=\"https://storage.googleapis.com/tensorflow_docs/Cirq/docs/$$$REPLACE_WITH_NOTEBOOK_PATH$$$\"><img src=\"https://quantumai.google/site-assets/images/buttons/download_icon_1x.png\" />Download notebook</a>\n",
+    "  </td>\n",
+    "</table>"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "bd9529db1c0b"
+   },
+   "outputs": [],
+   "source": [
+    "try:\n",
+    "    import cirq\n",
+    "except ImportError:\n",
+    "    print(\"installing cirq...\")\n",
+    "    !pip install --quiet cirq\n",
+    "    print(\"installed cirq.\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "name": "_template.ipynb",
+   "toc_visible": true
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

docs/dev/notebooks.md

@@ -0,0 +1,80 @@
+# Notebooks guidelines 
+
+Our guides and tutorials are frequently written using iPython Notebooks. The notebooks require specific formatting, are continuously tested (when possible) and we have a specific process to manage the lifecycle of a notebook before and after a Cirq release.    
+
+## Formatting 
+
+Formatting is easy, the script `check/nbformat` should tell you if your notebooks are formatted or not.
+You can apply the changes in one go with `check/nbformat --apply`. It is recommended to add this to your [git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), to save feedback time and CI resources. 
+
+## Output cells 
+
+Output cells typically should not be saved in the notebook. They will be generated for the final site.
+The exception to this rule are notebooks with external dependencies ([see below](#notebooks-with-external-dependencies)). 
+
+## Header
+
+We also expect a standard header to be included in all of our notebooks: 
+- the links to colab, github and the main site ([quantumai.google/cirq](https://quantumai.google/cirq))
+- optional package installation (you can assume Colab dependencies exist)
+
+
+Example header:
+
+![notebook header](../images/notebook_header.png)
+
+You can use [our template notebook](https://storage.googleapis.com/tensorflow_docs/Cirq/docs/_template.ipynb) to get started - please remember to change the `$$$REPLACE_WITH_TITLE$$$`, `$$$REPLACE_WITH_SITE_URL$$$` and `$$$REPLACE_WITH_NOTEBOOK_PATH$$$` placeholders.
+
+
+## Editing the tree nav on the site: _book.yaml
+
+If you are placing a guide or a tutorial on the site, please make sure you add an entry to the right place in the nav tree in [docs/_book.yaml](https://github.com/quantumlib/Cirq/blob/master/docs/_book.yaml).
+
+## Testing 
+
+Those notebooks that don't have any external dependencies (e.g. API calls, authentication) are tested on a continuous basis. 
+See the [`dev_tools/notebooks`](https://github.com/quantumlib/Cirq/tree/master/dev_tools/notebooks) directory for the two tests: 
+- [notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/notebook_test.py) - to test notebooks against the current branch
+- [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/isolated_notebook_test.py) - to test notebooks against the latest released version of Cirq
+
+## Notebooks with external dependencies 
+
+Unfortunately we have no easy way to test notebooks with external API dependencies, e.g. cirq.google's Engine API. 
+These notebooks should be excluded from both tests. 
+
+The site that generates the outputs for notebooks also can't handle external dependencies. 
+
+Thus, for notebooks with external dependencies, **all cells must have their outputs saved in the notebook file**. This ensures that the site pipeline will skip these notebooks.  
+
+## Lifecycle 
+
+You should configure notebooks differently depending on whether they rely on features in the pre-release build of cirq or not. 
+
+### Pre-release notebooks
+
+When you introduce a notebook that depends on pre-release features of Cirq, make sure to 
+
+ - mark the notebook at the top that `Note: this notebook relies on unreleased Cirq features. If you want to try these feature, make sure you install cirq via pip install cirq --pre`. 
+ - use `pip install cirq —pre`  in the installation instructions 
+ - make sure [notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/notebook_test.py) covers the notebook 
+ - exclude the notebook from the [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/isolated_notebook_test.py) by adding it to `NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES`
+
+### Stable notebooks
+
+When you introduce a notebook that only uses already released features of Cirq, make sure to
+ - use `pip install cirq` (NOT `pip install cirq --pre`)
+ - ensure the notebook is not excluded from either [notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/notebook_test.py) or [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/isolated_notebook_test.py)  (except if the notebook has external dependencies, in which case you should exclude this from both!)
+
+### Release 
+
+At release time, we change all the **pre-release notebooks** in bulk: 
+ - remove the pre-release notices
+ - change `pip install cirq —pre` to `pip install cirq`
+ - remove the exclusions in [isolated_notebook_test.py](https://github.com/quantumlib/Cirq/blob/master/dev_tools/notebooks/isolated_notebook_test.py) by making `NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES=[]`
+
+As all the notebooks have been tested continuously up to this point, the release notebook PR should pass without issues. 
+
+### Modifying stable notebooks 
+
+Modifications to stable notebooks are tested with dev_tools/notebooks/isolated_notebook_test.py.
+However, a stable notebook will become a pre-release notebook if a modification introduces dependency on unreleased features. In this case, follow the pre-release notebook guidelines accordingly. 

release.md

@@ -215,6 +215,10 @@ Using the information above, create the release on the
 [Release page](https://github.com/quantumlib/Cirq/releases).
 Be sure to include the whl file as an attachment.
 
+### Release PR for notebooks
+
+If there are unreleased notebooks, that are under testing (`NOTEBOOKS_DEPENDING_ON_UNRELEASED_FEATURES` is not empty in [dev_tools/notebooks/isolated_notebook_test.py](dev_tools/notebooks/isolated_notebook_test.py)), follow the steps in our [notebooks guide](docs/dev/notebooks.md).
+
 ### Email cirq-announce
 
 Lastly, email cirq-announce@googlegroups.com with the release notes