Allow sphinx building of docs (#64)

* Allow sphinx building of docs

The primary mechanism will be the `docs/` folder and
associated tensorflow-like build system. However, for
the interim we'll support building with sphinx since there's
little overhead.

In particular, sphinx will copy files from `docs/` to
`dev_tools/docs/sphinx`.

This PR also makes the following changes:

 - change copyright notice to bold from `<h6>`. `nbsphinx`
   was getting confused.
 - only install `recirq` in the notebook if it's not already
   installed. It's not nice to overwrite a user's environment!

* Fix notebook dependency code

* Intercept header at the source

* conf.py imports to the top

Author: mpharrigan

dev_tools/docs/sphinx/.gitignore

@@ -0,0 +1,3 @@
+tutorials/
+_static/g3618.png
+_static/recirq_logo_notext.png

dev_tools/docs/sphinx/_static/custom.css

@@ -11,3 +11,9 @@ div.body {
 div.document {
     width: 1220px;
 }
+
+/* nbsphinx strips the HTML from these cells
+   so they look bad */
+.tfo-notebook-buttons {
+    display: none;
+}

dev_tools/docs/sphinx/conf.py

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import os
+import re
 import shutil
+import subprocess
 
 project = 'ReCirq'
 copyright = '2020, Google Quantum'
@@ -97,10 +99,11 @@ def env_before_read_docs(app, env, docnames):
             cirq-results/qaoa-p1-landscape/2020-03-tutorial
 
     """
+    print("The following documents will be built:")
     print(docnames)
 
     def _order(docname):
-        if docname == 'Readout-Data-Collection':
+        if docname == 'tutorials/data_collection':
             # must come before others
             return -1
 
@@ -111,12 +114,14 @@ def _order(docname):
 
     docnames.sort(key=_order)
 
+    print("Since there are dependencies between them, they will be built in this order:")
     print(docnames)
 
-    if ('Readout-Data-Collection' in docnames
-            and 'Readout-Analysis' not in docnames):
-        # Mark the analysis notebook as changed
-        docnames.append('Readout-Analysis')
+    if ('tutorials/data_collection' in docnames
+            and 'tutorials/data_analysis' not in docnames):
+        print("Since tutorials/data_collection has changed, "
+              "also re-running tutorials/data_analysis")
+        docnames.append('tutorials/data_analysis')
 
     if 'qaoa/Tasks-Tutorial' in docnames:
         if 'qaoa/Precomputed-Analysis' not in docnames:
@@ -128,7 +133,9 @@ def _order(docname):
 
     print(docnames)
 
-    if 'Readout-Data-Collection' in docnames:
+    if 'tutorials/data_collection' in docnames:
+        print("Since tutorials/data_collection has changed, "
+              "deleting existing tutorial data.")
         from recirq.readout_scan import tasks as rs_tasks
         _rmtree_if_exists(f'{rs_tasks.DEFAULT_BASE_DIR}/2020-02-tutorial')
 
@@ -147,5 +154,22 @@ def _order(docname):
         _rmtree_if_exists(f'{qaoa_p1_tasks.DEFAULT_BASE_DIR}/2020-03-tutorial')
 
 
+
+REPO_DIR = subprocess.Popen(['git', 'rev-parse', '--show-toplevel'],
+                            stdout=subprocess.PIPE).communicate()[0].rstrip().decode('utf-8')
+
+
+def source_read(app, docname, source):
+    source[0] = re.sub(r'"##### (Copyright 20\d\d Google)"', r'"**\1**"', source[0])
+
+
 def setup(app):
+    FROM = f'{REPO_DIR}/docs'
+    TO = f'{REPO_DIR}/dev_tools/docs/sphinx'
+    from distutils.dir_util import copy_tree  # allows overwriting
+    copy_tree(f'{FROM}/tutorials', f'{TO}/tutorials')
+    shutil.copy(f'{FROM}/images/g3618.png', f'{TO}/_static/')
+    shutil.copy(f'{FROM}/images/recirq_logo_notext.png', f'{TO}/_static/')
+
     app.connect('env-before-read-docs', env_before_read_docs)
+    app.connect('source-read', source_read)

dev_tools/docs/sphinx/index.rst

@@ -26,8 +26,8 @@ navigation.
     :hidden:
 
     data_collection_idioms
-    Readout-Data-Collection
-    Readout-Analysis
+    tutorials/data_collection
+    tutorials/data_analysis
     best_practices
 
 .. toctree::

docs/tutorials/data_analysis.ipynb

@@ -99,7 +99,10 @@
       },
       "outputs": [],
       "source": [
-        "!pip install git+https://github.com/quantumlib/ReCirq"
+        "try:\n",
+        "    import recirq\n",
+        "except ImportError:\n",
+        "    !pip install git+https://github.com/quantumlib/ReCirq"
       ]
     },
     {
@@ -453,7 +456,6 @@
     },
     "kernelspec": {
       "display_name": "Python 3",
-      "language": "python",
       "name": "python3"
     }
   },

docs/tutorials/data_collection.ipynb

@@ -109,7 +109,10 @@
       },
       "outputs": [],
       "source": [
-        "!pip install git+https://github.com/quantumlib/ReCirq"
+        "try:\n",
+        "    import recirq\n",
+        "except ImportError:\n",
+        "    !pip install git+https://github.com/quantumlib/ReCirq"
       ]
     },
     {
@@ -437,7 +440,6 @@
     },
     "kernelspec": {
       "display_name": "Python 3",
-      "language": "python",
       "name": "python3"
     }
   },