From fc4bbd8f079465a31a7c1ea48cfe3f3dca8a5098 Mon Sep 17 00:00:00 2001
From: Monty Taylor <mordred@inaugust.com>
Date: Mon, 20 Nov 2017 12:03:39 -0600
Subject: [PATCH] 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                       |  5 ++
 .../library/sphinx_check_warning_is_error.py  | 80 +++++++++++++++++++
 roles/sphinx/tasks/main.yaml                  | 17 +++-
 3 files changed, 101 insertions(+), 1 deletion(-)
 create mode 100644 roles/sphinx/library/sphinx_check_warning_is_error.py

diff --git a/roles/sphinx/README.rst b/roles/sphinx/README.rst
index 7bfb34000..fcad72530 100644
--- a/roles/sphinx/README.rst
+++ b/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
 
diff --git a/roles/sphinx/library/sphinx_check_warning_is_error.py b/roles/sphinx/library/sphinx_check_warning_is_error.py
new file mode 100644
index 000000000..a86a63cc2
--- /dev/null
+++ b/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()
diff --git a/roles/sphinx/tasks/main.yaml b/roles/sphinx/tasks/main.yaml
index b057231f7..bdd51da07 100644
--- a/roles/sphinx/tasks/main.yaml
+++ b/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 }}"