Docs: debug broken docs build (googleapis#6007)

tseaver · web-flow · commit db2019aab457 · 2018-09-17T22:54:32.000-04:00
- Run docs build during nox w/ better debug output.
- Fix loop boundary bug in copying static HTML files.
- Log each file copied.
- Don't copy static HTML files on failed builds. The destination directory might not be present.
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,6 +28,10 @@
 import pkg_resources
 import shutil
 
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -325,18 +329,20 @@
 # See: https://tech.signavio.com/2017/managing-sphinx-redirects
 # HTML pages to be copied from source to target
 static_html_pages = [
-    'datastore.usage.html',
+    'datastore/usage.html',
     'bigquery/usage.html',
     'spanner/usage.html',
 ]
 
-def copy_static_html_pages(app, docname):
-    if app.builder.name == 'html':
+def copy_static_html_pages(app, exception):
+    if exception is None and app.builder.name == 'html':
         for static_html_page in static_html_pages:
             target_path = app.outdir + '/' + static_html_page
             src_path = app.srcdir + '/' + static_html_page
-        if os.path.isfile(src_path):
-            shutil.copyfile(src_path, target_path)
+            if os.path.isfile(src_path):
+                logger.info(
+                    'Copying static html: %s -> %s', src_path, target_path)
+                shutil.copyfile(src_path, target_path)
 
 def setup(app):
     app.connect('build-finished', copy_static_html_pages)
diff --git a/test_utils/scripts/update_docs.sh b/test_utils/scripts/update_docs.sh
@@ -25,7 +25,15 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 function build_docs {
     rm -rf docs/_build/
     rm -rf docs/bigquery/generated
-    sphinx-build -W -b html -d docs/_build/doctrees docs/ docs/_build/html/
+    # -W -> warnings as errors
+    # -T -> show full traceback on exception
+    # -N -> no color
+    sphinx-build \
+        -W -T -N \
+        -b html \
+        -d docs/_build/doctrees \
+        docs/ \
+        docs/_build/html/
     return $?
 }
 
