Documentation build broken with openstackdocstheme 1.20.0

[Ben Nemec]

The glance doc builds are all failing with the latest release of openstackdocstheme. The full traceback looks like this:

Traceback (most recent call last):
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/sphinx/setup_command.py", line 191, in run
    warningiserror=self.warning_is_error)
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/sphinx/application.py", line 234, in __init__
    self._init_builder()
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/sphinx/application.py", line 312, in _init_builder
    self.emit('builder-inited')
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/sphinx/application.py", line 489, in emit
    return self.events.emit(event, self, *args)
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/sphinx/events.py", line 79, in emit
    results.append(callback(*args))
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/openstackdocstheme/ext.py", line 209, in _builder_inited
    version = packaging.get_version(project_name)
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/pbr/packaging.py", line 740, in get_version
    version = _get_version_from_git(pre_version)
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/pbr/packaging.py", line 665, in _get_version_from_git
    git_dir = git._run_git_functions()
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/pbr/git.py", line 131, in _run_git_functions
    if _git_is_installed():
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/pbr/git.py", line 83, in _git_is_installed
    _run_shell_command(['git', '--version'])
  File "/opt/stack/glance/.tox/docs/lib/python2.7/site-packages/pbr/git.py", line 50, in _run_shell_command
    out = output.communicate()
  File "/usr/lib64/python2.7/subprocess.py", line 479, in communicate
    return self._communicate(input)
  File "/usr/lib64/python2.7/subprocess.py", line 1098, in _communicate
    stdout, stderr = self._communicate_with_poll(input)
  File "/usr/lib64/python2.7/subprocess.py", line 1128, in _communicate_with_poll
    poller = select.poll()
AttributeError: 'module' object has no attribute 'poll'

Although you have to dig into the output file to actually find that. The console only shows the last frame:

2018-03-29 18:29:54.962798 | ubuntu-xenial | Exception occurred:
2018-03-29 18:29:54.966922 | ubuntu-xenial | File "/usr/lib/python2.7/subprocess.py", line 1447, in _communicate_with_poll
2018-03-29 18:29:54.967107 | ubuntu-xenial | poller = select.poll()
2018-03-29 18:29:54.967324 | ubuntu-xenial | AttributeError: 'module' object has no attribute 'poll'

This seems to be related to eventlet monkey patching and was triggered by https://review.openstack.org/552069 That patch added a pbr import to openstackdocstheme, which apparently is happening before the eventlet monkey patching occurs. Then, after monkey patching, pbr attempts to call the subprocess module which fails because poll() has been patched out from under it.

At least, this is our working theory. Eventlet monkey patching is a complex beast so it's hard to say anything with absolute certainty.

I believe the best solution is to tweak Glance's monkey patching method to better conform to http://specs.openstack.org/openstack/openstack-specs/specs/eventlet-best-practices.html#monkey-patching Doing so seems to make the doc build work again, and will likely avoid other problems down the line.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/557819
Committed: https://git.openstack.org/cgit/openstack/glance/commit/?id=6310052486764922149427b43f1b359ad5aab23b
Submitter: Zuul
Branch: master

commit 6310052486764922149427b43f1b359ad5aab23b
Author: Ben Nemec <email address hidden>
Date: Thu Mar 29 19:51:39 2018 +0000

    Make eventlet monkey patching conform to best practices

    Per [1], eventlet monkey patching should happen as early as
    possible to avoid mismatches where a module was imported both before
    and after it was monkey patched. This is an exception to the import
    order rules that should maybe be more explicitly called out.

    In addition, partial monkey patching can be a problem, as shown in
    the discussion of the thread module from the same document. This
    seems to be contributing to the doc build problems that are
    occurring with the latest version of openstackdocstheme, so the
    partial monkey patching is also removed in favor of full patching.

    Change-Id: I0d2d9fb9f0b9d747ad1d955420f6ad129ebbfbcf
    1: http://specs.openstack.org/openstack/openstack-specs/specs/eventlet-best-practices.html#monkey-patching
    Closes-Bug: 1759935

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/glance 17.0.0.0b1 development milestone.