Hit bug 1472276 with pbr, which I was able to hack around, but then hit another error:

checking consistency... 2015-07-07 08:48:42.435 24115 CRITICAL nova [req-7340a971-0f5c-47dc-871b-7ef7ee54415a fake fake - - -] SphinxWarning: /home/mriedem/git/nova/doc/source/api/autoindex.rst:: WARNING: document isn't included in any toctree

2015-07-07 08:48:42.435 24115 ERROR nova Traceback (most recent call last):
2015-07-07 08:48:42.435 24115 ERROR nova   File "setup.py", line 29, in <module>
2015-07-07 08:48:42.435 24115 ERROR nova     pbr=True)
2015-07-07 08:48:42.435 24115 ERROR nova   File "/usr/lib/python2.7/distutils/core.py", line 151, in setup
2015-07-07 08:48:42.435 24115 ERROR nova     dist.run_commands()
2015-07-07 08:48:42.435 24115 ERROR nova   File "/usr/lib/python2.7/distutils/dist.py", line 953, in run_commands
2015-07-07 08:48:42.435 24115 ERROR nova     self.run_command(cmd)
2015-07-07 08:48:42.435 24115 ERROR nova   File "/usr/lib/python2.7/distutils/dist.py", line 972, in run_command
2015-07-07 08:48:42.435 24115 ERROR nova     cmd_obj.run()
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/pbr/builddoc.py", line 198, in run
2015-07-07 08:48:42.435 24115 ERROR nova     self._sphinx_run()
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/pbr/builddoc.py", line 152, in _sphinx_run
2015-07-07 08:48:42.435 24115 ERROR nova     app.build(force_all=self.all_files)
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/application.py", line 216, in build
2015-07-07 08:48:42.435 24115 ERROR nova     self.builder.build_all()
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 177, in build_all
2015-07-07 08:48:42.435 24115 ERROR nova     self.build(None, summary='all source files', method='all')
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 261, in build
2015-07-07 08:48:42.435 24115 ERROR nova     self.env.check_consistency()
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/environment.py", line 1677, in check_consistency
2015-07-07 08:48:42.435 24115 ERROR nova     self.warn(docname, 'document isn\'t included in any toctree')
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/environment.py", line 257, in warn
2015-07-07 08:48:42.435 24115 ERROR nova     self._warnfunc(msg, (docname, lineno))
2015-07-07 08:48:42.435 24115 ERROR nova   File "/home/mriedem/git/nova/.tox/docs/local/lib/python2.7/site-packages/sphinx/application.py", line 268, in warn
2015-07-07 08:48:42.435 24115 ERROR nova     raise SphinxWarning(warntext)
2015-07-07 08:48:42.435 24115 ERROR nova SphinxWarning: /home/mriedem/git/nova/doc/source/api/autoindex.rst:: WARNING: document isn't included in any toctree
2015-07-07 08:48:42.435 24115 ERROR nova 
2015-07-07 08:48:42.435 24115 ERROR nova 


Which is what was actually removed in jogo's original change: https://review.openstack.org/#/c/121737/2/doc/source/index.rst

There might be away to ignore the toc index for that specific file in a configuration change, else we'd set warnerrors=False in setup.cfg and that would ignore it, but then we lose any validation on the docstrings in our code which is nice to have so our docs look OK.