Notebooks guide

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": [
+    "# Quantum variational algorithm"
+   ]
+  },
+  {
+   "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

@@ -5,30 +5,41 @@ Our guides and tutorials are frequently written using iPython Notebooks. The not
 ## 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 you [git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), to save feedback time and CI resources. 
+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). 
+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)
+- 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_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. authentication) can be executed in an isolated environment are being tested on a continuous basis. 
-See the `dev_tools/notebooks` directory for the two tests: 
-- notebook_tests.py - to test notebooks against the current branch
-- isolated_notebook_tests.py - to test notebooks against the latest released version of Cirq
+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 way to test notebooks yet easily with external API dependencies, e.g. cirq.google's Engine API. 
+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. 
@@ -37,7 +48,7 @@ Thus, for notebooks with external dependencies, **all cells must have their outp
 
 ## Lifecycle 
 
-Notebooks are handled differently based on whether they rely on features in the pre-release build of cirq or not. 
+We should follow different configurations for notebooks depending on whether they rely on features in the pre-release build of cirq or not. 
 
 Pre-release notebooks: 
  - 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`. 

release.md

@@ -215,13 +215,13 @@ 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
 and an announcement of the new version.
 
 Congratulate yourself for a well done release!
-
-### Post release PR for notebooks
-
-If there are unreleased notebooks (`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).