DOC: Make sphinx fail the build when --warnings-are-errors is set (#24523)

Author: datapythonista

doc/make.py

@@ -124,13 +124,12 @@ def _sphinx_build(self, kind):
         if self.num_jobs:
             cmd += ['-j', str(self.num_jobs)]
         if self.warnings_are_errors:
-            cmd.append('-W')
+            cmd += ['-W', '--keep-going']
         if self.verbosity:
             cmd.append('-{}'.format('v' * self.verbosity))
         cmd += ['-d', os.path.join(BUILD_PATH, 'doctrees'),
                 SOURCE_PATH, os.path.join(BUILD_PATH, kind)]
-        cmd = ['sphinx-build', SOURCE_PATH, os.path.join(BUILD_PATH, kind)]
-        self._run_os(*cmd)
+        return subprocess.call(cmd)
 
     def _open_browser(self, single_doc_html):
         """
@@ -144,13 +143,14 @@ def html(self):
         """
         Build HTML documentation.
         """
-        self._sphinx_build('html')
+        ret_code = self._sphinx_build('html')
         zip_fname = os.path.join(BUILD_PATH, 'html', 'pandas.zip')
         if os.path.exists(zip_fname):
             os.remove(zip_fname)
 
         if self.single_doc_html is not None:
             self._open_browser(self.single_doc_html)
+        return ret_code
 
     def latex(self, force=False):
         """
@@ -159,7 +159,7 @@ def latex(self, force=False):
         if sys.platform == 'win32':
             sys.stderr.write('latex build has not been tested on windows\n')
         else:
-            self._sphinx_build('latex')
+            ret_code = self._sphinx_build('latex')
             os.chdir(os.path.join(BUILD_PATH, 'latex'))
             if force:
                 for i in range(3):
@@ -170,12 +170,13 @@ def latex(self, force=False):
                                  '"build/latex/pandas.pdf" for problems.')
             else:
                 self._run_os('make')
+            return ret_code
 
     def latex_forced(self):
         """
         Build PDF documentation with retries to find missing references.
         """
-        self.latex(force=True)
+        return self.latex(force=True)
 
     @staticmethod
     def clean():
@@ -257,7 +258,7 @@ def main():
 
     builder = DocBuilder(args.num_jobs, not args.no_api, args.single,
                          args.verbosity, args.warnings_are_errors)
-    getattr(builder, args.command)()
+    return getattr(builder, args.command)()
 
 
 if __name__ == '__main__':

doc/source/conf.py

@@ -738,6 +738,10 @@ def process_class_docstrings(app, what, name, obj, options, lines):
     # suppress this warning.
     'app.add_directive'
 ]
+if pattern:
+    # When building a single document we don't want to warn because references
+    # to other documents are unknown, as it's expected
+    suppress_warnings.append('ref.ref')
 
 
 def rstjinja(app, docname, source):