Treat Sphinx warnings as errors when building docs on Travis

.travis.yml

@@ -43,7 +43,7 @@ script:
   - if [[ $BUILD_DOCS == false ]]; then mkdir ../tmp_test_dir; fi
   - if [[ $BUILD_DOCS == false ]]; then cd ../tmp_test_dir; fi
   - if [[ $BUILD_DOCS == false ]]; then gdb -return-child-result -batch -ex r -ex bt --args python ../matplotlib/tests.py -sv --processes=8 --process-timeout=300 $TEST_ARGS; fi
-  - if [[ $BUILD_DOCS == true ]]; then cd doc; python make.py html --small; fi
+  - if [[ $BUILD_DOCS == true ]]; then cd doc; python make.py html --small --warningsaserrors; fi
   # We don't build the LaTeX docs here, so linkchecker will complain
   - if [[ $BUILD_DOCS == true ]]; then touch build/html/Matplotlib.pdf; fi
   - if [[ $BUILD_DOCS == true ]]; then linkchecker build/html/index.html; fi

doc/conf.py

@@ -34,7 +34,7 @@
               'sphinxext.github',
               'numpydoc']
 
-exclude_patterns = ['api/api_changes/README.rst', 'users/whats_new/README.rst']
+exclude_patterns = ['api/api_changes/*', 'users/whats_new/*']
 
 # Use IPython's console highlighting by default
 try:

doc/make.py

@@ -6,7 +6,7 @@
 import shutil
 import sys
 import re
-
+import argparse
 
 def copy_if_out_of_date(original, derived):
     if (not os.path.exists(derived) or
@@ -43,6 +43,8 @@ def html(buildername='html'):
         options = "-D plot_formats=\"[('png', 80)]\""
     else:
         options = ''
+    if warnings_as_errors:
+        options = options + ' -W'
     if os.system('sphinx-build %s -b %s -d build/doctrees . build/%s' % (options, buildername, buildername)):
         raise SystemExit("Building HTML failed.")
 
@@ -136,6 +138,7 @@ def all():
 
 
 small_docs = False
+warnings_as_errors = False
 
 # Change directory to the one containing this file
 current_dir = os.getcwd()
@@ -174,17 +177,28 @@ def all():
             'as spurious changes in your \'git status\':\n\t{}' 
                     .format('\n\t'.join(symlink_warnings)))
 
-if len(sys.argv)>1:
-    if '--small' in sys.argv[1:]:
-        small_docs = True
-        sys.argv.remove('--small')
-    for arg in sys.argv[1:]:
-        func = funcd.get(arg)
+parser = argparse.ArgumentParser(description='Build matplotlib docs')
+parser.add_argument("cmd", help=("Command to execute. Can be multiple. "
+                    "Valid options are: %s" % (funcd.keys())), nargs='*')
+parser.add_argument("--small",
+                    help="Smaller docs with only low res png figures",
+                    action="store_true")
+parser.add_argument("--warningsaserrors",
+                    help="Turn Sphinx warnings into errors",
+                    action="store_true")
+args = parser.parse_args()
+if args.small:
+    small_docs = True
+if args.warningsaserrors:
+    warnings_as_errors = True
+
+if args.cmd:
+    for command in args.cmd:
+        func = funcd.get(command)
         if func is None:
-            raise SystemExit('Do not know how to handle %s; valid args are %s'%(
-                    arg, funcd.keys()))
+            raise SystemExit(('Do not know how to handle %s; valid commands'
+                              ' are %s' % (command, funcd.keys())))
         func()
 else:
-    small_docs = False
     all()
 os.chdir(current_dir)