Update the sphinx python package sets

The role will now use a known functional set of packages based on the
version of python being defined.

To allow users to add packages to a known functional version of
sphinx the variable `doc_building_extra_packages` has been added.
This option will union with `doc_building_packages`, installing all
python packages in a single set.

The releasenotes pre playbook has been updated so that it no longer
overrides the default package set when calling the "ensure-sphinx"
role. The playbook will now use the `doc_building_extra_packages`
option and include only the additional packages it needs. This change
allows folks to rely on the role to setup sphinx correctly without
needing to overriding everything.

Change-Id: Ib3d2fda164b173c82f17fabc20814753bfeaec6e
Signed-off-by: Kevin Carter <kecarter@redhat.com>

playbooks/releasenotes/pre.yaml

@@ -4,7 +4,6 @@
       bindep_profile: doc
       bindep_dir: "{{ zuul_work_dir }}"
     - role: ensure-sphinx
-      doc_building_packages:
-        - sphinx
+      doc_building_extra_packages:
         - reno
     - revoke-sudo

roles/ensure-sphinx/README.rst

@@ -12,9 +12,16 @@ All pip installs are done with a provided constraints file, if given.
    Optional path to a pip constraints file for installing python libraries.
 
 .. zuul:rolevar:: doc_building_packages
-   :default: ['sphinx']
+   :default: ``list``
 
-   List of python packages to install for building docs.
+   List of python packages to install for building docs. The default
+   package list is based on the python version in use.
+
+.. zuul:rolevar:: doc_building_extra_packages
+   :default: ``list``
+
+   List of python additional packages to install for building docs.
+   By default this list is empty.
 
 .. zuul:rolevar:: sphinx_python
    :default: python2

roles/ensure-sphinx/defaults/main.yaml

@@ -1,5 +1,5 @@
 zuul_work_dir: "{{ zuul.project.src_dir }}"
 zuul_work_virtualenv: "{{ ansible_user_dir }}/.venv"
 sphinx_python: python2
-doc_building_packages:
-  - sphinx
+doc_building_packages: "{{ _doc_building_packages | default([]) }}"
+doc_building_extra_packages: []

roles/ensure-sphinx/tasks/main.yaml

@@ -1,3 +1,5 @@
+---
+
 # NOTE: gettext command is provided by gettext-base package,
 # so we need to check a command provided by gettext package.
 - name: Check for gettext installed
@@ -33,15 +35,17 @@
       done
   register: requirements_file
 
+- name: Gather python version variables
+  include_vars: "{{ sphinx_python.split('.')[0] }}.yaml"
+
 # TODO(dmsimard) Don't assume virtualenv is installed
 - name: Install base doc building packages
   pip:
-    name: "{{ item }}"
+    name: "{{ doc_building_packages | union(doc_building_extra_packages) }}"
     chdir: "{{ zuul_work_dir }}"
     virtualenv: "{{ zuul_work_virtualenv }}"
     virtualenv_python: "{{ sphinx_python }}"
     extra_args: "{{ upper_constraints | default(omit) }}"
-  with_items: "{{ doc_building_packages }}"
 
 # TODO(dmsimard) Don't assume virtualenv is installed
 - name: Install found doc requirements

roles/ensure-sphinx/vars/python2.yaml

@@ -0,0 +1,2 @@
+_doc_building_packages:
+  - sphinx<2.0

roles/ensure-sphinx/vars/python3.yaml

@@ -0,0 +1,2 @@
+_doc_building_packages:
+  - sphinx