Add support for warning-is-error to sphinx role

Sphinx currently does not have a way to set warning-is-error in a config
file for builds that do not use python setup.py build_sphinx. It's
perfectly reasonable to use Sphinx for non-python languages, but putting
a setup.cfg into those projects is a bit weird. While we wait on getting
a config setting upstream, read the value out of setup.cfg ourselves if
it exists. This will let existing python projects with the setting work
as we expect, but will also let us just set a zuul variable for
non-python projects if we decide to not just put a setup.cfg in them.

Change-Id: Ie65dcb42c48e6a962f6715f7483ef3758caf2965

roles/sphinx/README.rst

@@ -17,6 +17,11 @@ Run sphinx to generate documentation
 
    Which sphinx builders to run.
 
+.. zuul:rolevar:: sphinx_warning_is_error
+
+   Whether to treat sphinx build warnings as errors. Defaults to undefined
+   which means to attempt to find the setting in a setup.cfg file.
+
 .. zuul:rolevar:: zuul_work_virtualenv
    :default: ~/.venv
 

roles/sphinx/library/sphinx_check_warning_is_error.py

@@ -0,0 +1,80 @@
+#!/usr/bin/python
+
+# Copyright (c) 2017 Red Hat
+#
+# This module is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This software is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this software.  If not, see <http://www.gnu.org/licenses/>.
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: sphinx_check_warning_is_error
+short_description: Read the warning-is-error setting from setup.cfg
+author: Monty Taylor (@mordred)
+description:
+  - When running sphinx using sphinx-build and not using python setup.py
+    build_sphinx there is no way to set warning-is-error in a config file.
+    The sphinx-build command expects the -W flag to be passed. Read the setting
+    from a setup.cfg file if one exists.
+requirements:
+  - "python >= 3.5"
+options:
+  project_dir:
+    description:
+      - The directory in which the project we care about is in.
+    required: true
+    type: str
+'''
+
+try:
+    import configparser
+except ImportError:
+    import ConfigParser as configparser
+
+import os
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            project_dir=dict(required=True, type='str'),
+        )
+    )
+    project_dir = module.params['project_dir']
+
+    if not os.path.exists(os.path.join(project_dir, 'setup.cfg')):
+        module.exit_json(
+            changed=False,
+            warning_is_error=False,
+            msg="No setup.cfg, no action needed")
+
+    try:
+        c = configparser.ConfigParser()
+        c.read(os.path.join(project_dir, 'setup.cfg'))
+        warning_is_error = c.getboolean('build_sphinx', 'warning-is-error')
+    except Exception:
+        module.exit_json(
+            changed=False,
+            warning_is_error=False,
+            msg="Setting not found in setup.cfg, defaulting to false")
+    module.exit_json(
+        changed=False,
+        warning_is_error=warning_is_error,
+        msg="warning_is_error setting found in build_sphinx section")
+
+
+if __name__ == '__main__':
+    main()

roles/sphinx/tasks/main.yaml

@@ -1,6 +1,21 @@
+- name: Attempt to get warning-is-error from config file
+  when: sphinx_warning_is_error is not defined
+  sphinx_check_warning_is_error:
+    project_dir: "{{ zuul_work_dir }}"
+  register: check_result
+
+- name: Set sphinx_warning_is_error
+  when: sphinx_warning_is_error is not defined
+  set_fact:
+    sphinx_warning_is_error: "{{ check_result.warning_is_error }}"
+
 - name: Run sphinx
   command:
-    cmd: "{{ zuul_work_virtualenv }}/bin/sphinx-build -b {{ item }} {{ sphinx_source_dir }} {{ sphinx_build_dir }}/{{ item }}"
+    cmd: >
+      {{ zuul_work_virtualenv }}/bin/sphinx-build
+        -b {{ item }}
+        {% if sphinx_warning_is_error %} -W {% endif %}
+        {{ sphinx_source_dir }} {{ sphinx_build_dir }}/{{ item }}
     chdir: "{{ zuul_work_dir }}"
   with_items: "{{ sphinx_builders }}"