More sphinx docs (#65)

* 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

* Build the rest of stuff using Sphinx

* Rest of the notebooks

 - optional recirq installation
 - save outputs (for now) in long-running notebooks

* re-run nbfomt; remove private_outputs

Author: mpharrigan

dev_tools/docs/sphinx/.gitignore

@@ -1,3 +1,8 @@
 tutorials/
+qaoa/*.ipynb
+qaoa/images
+
 _static/g3618.png
 _static/recirq_logo_notext.png
+best_practices.md
+data_collection_idioms.md

dev_tools/docs/sphinx/conf.py

@@ -25,7 +25,8 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'recommonmark',
 ]
 
 nbsphinx_allow_errors = False
@@ -107,7 +108,7 @@ def _order(docname):
             # must come before others
             return -1
 
-        if docname == 'qaoa/Tasks-Tutorial':
+        if docname == 'qaoa/tasks':
             # must come before others
             return -1
         return 0
@@ -123,13 +124,13 @@ def _order(docname):
               "also re-running tutorials/data_analysis")
         docnames.append('tutorials/data_analysis')
 
-    if 'qaoa/Tasks-Tutorial' in docnames:
-        if 'qaoa/Precomputed-Analysis' not in docnames:
+    if 'qaoa/tasks' in docnames:
+        if 'qaoa/precomputed_analysis' not in docnames:
             # Mark the analysis notebook as changed
-            docnames.append('qaoa/Precomputed-Analysis')
-        if 'qaoa/Landscape-Analysis' not in docnames:
+            docnames.append('qaoa/precomputed_analysis')
+        if 'qaoa/landscape_analysis' not in docnames:
             # Mark the analysis notebook as changed
-            docnames.append('qaoa/Landscape-Analysis')
+            docnames.append('qaoa/landscape_analysis')
 
     print(docnames)
 
@@ -139,7 +140,7 @@ def _order(docname):
         from recirq.readout_scan import tasks as rs_tasks
         _rmtree_if_exists(f'{rs_tasks.DEFAULT_BASE_DIR}/2020-02-tutorial')
 
-    if 'qaoa/Tasks-Tutorial' in docnames and nbsphinx_execute == 'always':
+    if 'qaoa/tasks' in docnames and nbsphinx_execute == 'always':
         # Clear data that's already been collected, but only if we're actually
         # executing this notebook. This notebook is saved pre-executed, so
         # set environment variable NBSPHINX_EXECUTE_NOTEBOOKS to 'auto' to
@@ -166,10 +167,15 @@ def source_read(app, docname, source):
 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/')
 
+    shutil.copy(f'{FROM}/data_collection_idioms.md', f'{TO}/')
+    shutil.copy(f'{FROM}/best_practices.md', f'{TO}/')
+
+    from distutils.dir_util import copy_tree  # allows overwriting
+    copy_tree(f'{FROM}/tutorials', f'{TO}/tutorials')
+    copy_tree(f'{FROM}/qaoa', f'{TO}/qaoa')
+
     app.connect('env-before-read-docs', env_before_read_docs)
     app.connect('source-read', source_read)

dev_tools/docs/sphinx/index.rst

@@ -42,11 +42,11 @@ navigation.
     :caption: QAOA
     :hidden:
 
-    qaoa/Example-Problems
-    qaoa/Tasks-Tutorial
-    qaoa/Precomputed-Analysis
-    qaoa/Landscape-Analysis
-    qaoa/hardware-grid-qaoa-circuits
+    qaoa/example_problems
+    qaoa/tasks
+    qaoa/precomputed_analysis
+    qaoa/landscape_analysis
+    qaoa/hardware_grid_circuits
     qaoa/problem_generation_tasks
     qaoa/angle_precomputation_tasks
-    qaoa/Routing-with-Tket
+    qaoa/routing_with_tket

docs/qaoa/example_problems.ipynb

@@ -132,7 +132,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"
       ]
     },
     {
@@ -311,13 +314,11 @@
   "metadata": {
     "colab": {
       "name": "example_problems.ipynb",
-      "private_outputs": true,
       "provenance": [],
       "toc_visible": true
     },
     "kernelspec": {
       "display_name": "Python 3",
-      "language": "python",
       "name": "python3"
     }
   },

docs/qaoa/hardware_grid_circuits.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"
       ]
     },
     {
@@ -766,13 +769,11 @@
   "metadata": {
     "colab": {
       "name": "hardware_grid_circuits.ipynb",
-      "private_outputs": true,
       "provenance": [],
       "toc_visible": true
     },
     "kernelspec": {
       "display_name": "Python 3",
-      "language": "python",
       "name": "python3"
     }
   },