From 167cc321f4d305e4e36d47ea1e87205310696843 Mon Sep 17 00:00:00 2001 From: Kevin Carter Date: Wed, 3 Jul 2019 11:31:47 -0500 Subject: [PATCH] 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 --- playbooks/releasenotes/pre.yaml | 3 +-- roles/ensure-sphinx/README.rst | 11 +++++++++-- roles/ensure-sphinx/defaults/main.yaml | 4 ++-- roles/ensure-sphinx/tasks/main.yaml | 8 ++++++-- roles/ensure-sphinx/vars/python2.yaml | 2 ++ roles/ensure-sphinx/vars/python3.yaml | 2 ++ 6 files changed, 22 insertions(+), 8 deletions(-) create mode 100644 roles/ensure-sphinx/vars/python2.yaml create mode 100644 roles/ensure-sphinx/vars/python3.yaml diff --git a/playbooks/releasenotes/pre.yaml b/playbooks/releasenotes/pre.yaml index 9cc344eda..bbd1a5b14 100644 --- a/playbooks/releasenotes/pre.yaml +++ b/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 diff --git a/roles/ensure-sphinx/README.rst b/roles/ensure-sphinx/README.rst index fff853275..262c9106c 100644 --- a/roles/ensure-sphinx/README.rst +++ b/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 diff --git a/roles/ensure-sphinx/defaults/main.yaml b/roles/ensure-sphinx/defaults/main.yaml index 661a8dd51..83b224055 100644 --- a/roles/ensure-sphinx/defaults/main.yaml +++ b/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: [] diff --git a/roles/ensure-sphinx/tasks/main.yaml b/roles/ensure-sphinx/tasks/main.yaml index ca1392491..94c3cc2e3 100644 --- a/roles/ensure-sphinx/tasks/main.yaml +++ b/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 diff --git a/roles/ensure-sphinx/vars/python2.yaml b/roles/ensure-sphinx/vars/python2.yaml new file mode 100644 index 000000000..ab8dbc2cc --- /dev/null +++ b/roles/ensure-sphinx/vars/python2.yaml @@ -0,0 +1,2 @@ +_doc_building_packages: + - sphinx<2.0 diff --git a/roles/ensure-sphinx/vars/python3.yaml b/roles/ensure-sphinx/vars/python3.yaml new file mode 100644 index 000000000..ec2e3b182 --- /dev/null +++ b/roles/ensure-sphinx/vars/python3.yaml @@ -0,0 +1,2 @@ +_doc_building_packages: + - sphinx