Handle projects still using pbr autodoc_index_modules

There are a non-zero number of projects in OpenStack that are still
using pbr.autodoc_index_modules. Switching to the new sphinx build job
breaks them if they have warning-is-error turned on, as their docs are
expecting a reference to the autogenerated module doc indexes.

We should come up with a better solution for migrating them ... probably
a sphinx plugin that one can use with some options and whatnot. Or we
can commit a copy of the generated autoindex file and then treat it as
actual source code moving forward.

For now we need to run those projects with the pbr modified sphinx
builder. This adds support to the setup.cfg value lookup module
for looking up autodoc_index_modules and plumbs it in to the sphinx
invocation.

A note has also been left with an idea for how to simplify this and
remove the python module (we can ini lookup on the executor) but
implementing that is left as an exercise for later.

Change-Id: Ie0c9f24df09255e871f904e079b68809144b36b4

roles/sphinx/tasks/main.yaml

@@ -8,6 +8,7 @@
   when: sphinx_warning_is_error is not defined
   set_fact:
     sphinx_warning_is_error: "{{ check_result.warning_is_error }}"
+    sphinx_pbr_autodoc: "{{ check_result.autodoc_index_modules }}"
 
 - name: Run sphinx
   shell:
@@ -21,6 +22,19 @@
         {{ sphinx_source_dir }} {{ sphinx_build_dir }}/{{ item }}
     chdir: "{{ zuul_work_dir }}"
   with_items: "{{ sphinx_builders }}"
+  when: not sphinx_pbr_autodoc
+
+# TODO(mordred) Remove this when we get projects off of the pbr autoindex
+- name: Run sphinx using legacy pbr runner
+  shell:
+    executable: /bin/bash
+    cmd: |
+      # Source the activate file so that sphinx subcommands have the correct
+      # paths set.
+      source {{ zuul_work_virtualenv }}/bin/activate
+      python setup.py build_sphinx
+    chdir: "{{ zuul_work_dir }}"
+  when: sphinx_pbr_autodoc
 
 - name: Check for whereto
   stat: