tripleo-common docs job broken on stable/ocata

[James Slagle]

All runs of gate-tripleo-common-docs-ubuntu-xenial
on tripleo-common for stable/ocata fail with:

2017-08-07 14:55:28.131675 | File "setup.py", line 29, in <module>
2017-08-07 14:55:28.131707 | pbr=True)
2017-08-07 14:55:28.131758 | File "/usr/lib/python2.7/distutils/core.py", line 151, in setup
2017-08-07 14:55:28.132558 | dist.run_commands()
2017-08-07 14:55:28.132637 | File "/usr/lib/python2.7/distutils/dist.py", line 953, in run_commands
2017-08-07 14:55:28.134490 | self.run_command(cmd)
2017-08-07 14:55:28.134568 | File "/usr/lib/python2.7/distutils/dist.py", line 972, in run_command
2017-08-07 14:55:28.134601 | cmd_obj.run()
2017-08-07 14:55:28.134691 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/pbr/builddoc.py", line 200, in run
2017-08-07 14:55:28.134747 | self._sphinx_run()
2017-08-07 14:55:28.134844 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/pbr/builddoc.py", line 151, in _sphinx_run
2017-08-07 14:55:28.134900 | app.build(force_all=self.all_files)
2017-08-07 14:55:28.134996 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/application.py", line 261, in build
2017-08-07 14:55:28.135032 | self.builder.build_all()
2017-08-07 14:55:28.135127 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 211, in build_all
2017-08-07 14:55:28.135182 | self.build(None, summary='all source files', method='all')
2017-08-07 14:55:28.135278 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 322, in build
2017-08-07 14:55:28.135327 | self.write(docnames, list(updated_docnames), method)
2017-08-07 14:55:28.135434 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 360, in write
2017-08-07 14:55:28.135480 | self._write_serial(sorted(docnames), warnings)
2017-08-07 14:55:28.135577 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 368, in _write_serial
2017-08-07 14:55:28.135615 | self.write_doc(docname, doctree)
2017-08-07 14:55:28.135708 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/builders/html.py", line 443, in write_doc
2017-08-07 14:55:28.135750 | self.docwriter.write(doctree, destination)
2017-08-07 14:55:28.135843 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/docutils/writers/__init__.py", line 80, in write
2017-08-07 14:55:28.135874 | self.translate()
2017-08-07 14:55:28.135966 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/sphinx/writers/html.py", line 53, in translate
2017-08-07 14:55:28.136058 | self.document.walkabout(visitor)
2017-08-07 14:55:28.136155 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/docutils/nodes.py", line 187, in walkabout
2017-08-07 14:55:28.136194 | visitor.dispatch_departure(self)
2017-08-07 14:55:28.136289 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/docutils/nodes.py", line 1895, in dispatch_departure
2017-08-07 14:55:28.136321 | return method(node)
2017-08-07 14:55:28.136420 | File "/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/local/lib/python2.7/site-packages/docutils/writers/_html_base.py", line 736, in depart_document
2017-08-07 14:55:28.136472 | assert not self.context, 'len(context) = %s' % len(self.context)
2017-08-07 14:55:28.136509 | AssertionError: len(context) = 1
2017-08-07 14:55:28.208605 | ERROR: InvocationError: '/home/jenkins/workspace/gate-tripleo-common-docs-ubuntu-xenial/.tox/venv/bin/python setup.py build_sphinx'
2017-08-07 14:55:28.208884 | ___________________________________ summary ____________________________________
2017-08-07 14:55:28.208937 | ERROR: venv: commands failed
2017-08-07 14:55:28.222887 | [Zuul] Task exit code: 1
2017-08-07 14:55:30.759732 | [Zuul] Job complete, result: FAILURE

this blocks us from merging any code in stable/ocata for tripleo-common

[James Slagle (james-slagle)]

the quick fix seems to be to remove the svg image link for the repo tags from README.rst:

.. image:: http://governance.openstack.org/badges/tripleo-common.svg
    :target: http://governance.openstack.org/reference/tags/index.html

If you remove those 2 lines the build passes for me locally at least.

I also found this issue:
https://github.com/sphinx-doc/sphinx/issues/3212

So it's been fixed in a newer sphinx, which we obviously don't have in tripleo-common due to the pin of sphinx in test-requirements.txyt

[Ben Nemec (bnemec)]

Workaround proposed at https://review.openstack.org/#/c/491576/

[Flavio Percoco (flaper87)]

The best fix I can think of is the workaround proposed. It's weird this issue was not hit before, though. I remember dealing with it upstream and updating docutils.

Arguably, the tags are useful only for master as they represent the *current* status of the project. Ultimately, we should find a way to make tag these badges with the releases.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/491576
Committed: https://git.openstack.org/cgit/openstack/tripleo-common/commit/?id=c535ca47d8e4275f22bc6e813f71c57d6d0119a3
Submitter: Jenkins
Branch: stable/ocata

commit c535ca47d8e4275f22bc6e813f71c57d6d0119a3
Author: James Slagle <email address hidden>
Date: Mon Aug 7 14:57:27 2017 -0400

    Remove svg links

    These links are breaking the docs build for tripleo-common on
    stable/ocata effectively blocking us from merging any code on that
    branch.

    The bug was reported to sphinx and has been fixed:
    https://github.com/sphinx-doc/sphinx/issues/3212

    However, we don't have the newer version of sphinx in stable/ocata due
    to the pin in test-requirements.txt coming from the global requirements
    repo.

    Change-Id: I06da2e01b898a303c445331387850a8cf1e24827
    Partial-Bug: #1709152