pbr + Sphinx 1.6+ ignores the '[sphinx_build] builders' setuptools option

[Stephen Finucane]

Previously, the 'builders' configuration option could be used to specify multiple builders that Sphinx would use one by one. Sphinx 1.6 added a similar feature and we now ignore this option when running with Sphinx 1.6. However, Sphinx uses the 'builder' configuration option, not 'builders', and we give no warning that 'builders' is no longer supported.

We should probably keep using 'builders', if present, until such a time as we can deprecate the option fully.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/481620

[OpenStack Infra (hudson-openstack)]

Related fix proposed to branch: master
Review: https://review.openstack.org/481621

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/481620
Committed: https://git.openstack.org/cgit/openstack-dev/pbr/commit/?id=c59fad9c883c85af02b663f5c25b297f54f992d1
Submitter: Jenkins
Branch: master

commit c59fad9c883c85af02b663f5c25b297f54f992d1
Author: Stephen Finucane <email address hidden>
Date: Fri Jul 7 11:02:36 2017 +0100

    builddoc: Use '[sphinx_build] builders' with Sphinx < 1.6

    In 'c024066', we resolved an issue with pbr and Sphinx 1.6+ and
    implicitly started using Sphinx 1.6's support for declaring multiple
    builders as part of the setuptools plugin. However, in doing so, we
    neglected to provide a migration path for folks who were using the older
    option. This meant folks using the '[sphinx_build] builders' option
    would see a breaking change in behavior when upgrading to a pbr release
    including the above change. Resolve this issue now.

    Note that we want to deprecate support for this option in the future,
    but doing so is not a backportable change and will be done separately.

    Change-Id: Ic2fe67f932ba26b665110ae66431a5359fc50016
    Closes-Bug: #1702872
    Related-Bug: #1691129

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/481621
Committed: https://git.openstack.org/cgit/openstack-dev/pbr/commit/?id=cc703f4926e0a4d4dd034176b523923e5a09492a
Submitter: Jenkins
Branch: master

commit cc703f4926e0a4d4dd034176b523923e5a09492a
Author: Stephen Finucane <email address hidden>
Date: Fri Jul 7 11:14:39 2017 +0100

    Deprecate support for Sphinx < 1.6

    We don't want to support older versions of Sphinx forever. While
    OpenStack's global requirements have been bumped to Sphinx 1.6, there
    are non-OpenStack users in the wild. Give them a chance to upgrade to
    the newer version before we completely remove support.

    This also gives us a chance to deprecate the '[sphinx_build] builders'
    setuptools option, which is no longer necessary with Sphinx 1.6+. Do
    this. The documentation is updated to reflect this (and some references
    to a "custom" 'source_dir' option removed, as it's not at all specific
    to pbr).

    Change-Id: I18bbf693bca2f6e49d822ae2940d2170a2b90ce9
    Related-Bug: #1702872

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack-dev/pbr 4.0.0 release.