add the ability to skip execution of notebooks when building docs (#319)

Author: zingale

docs/source/conf.py

@@ -57,7 +57,12 @@
 templates_path = ['_templates']
 
 # always execute notebooks
-nbsphinx_execute = 'always'
+env_skip_execute = os.getenv("SKIP_EXECUTE")
+
+if not env_skip_execute:
+    nbsphinx_execute = 'always'
+else:
+    nb_execution_mode = "never"
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:

docs/source/help.rst

@@ -40,6 +40,22 @@ to squash commits upon merge to have a clean history.  *Please ensure
 that your PR title and first post are descriptive, since these will be
 used for a squashed commit message.*
 
+Building Docs
+-------------
+
+The source for the documentation is in `pyro/docs` and can be built via:
+
+```
+make html
+```
+
+By default, this will execute all of the notebooks that are used in the docs,
+which can take time.  To skip the execution, you can build as:
+
+```
+make SKIP_EXECUTE=TRUE html
+```
+
 Discussions
 -----------