documentation build output includes a lot of warnings

[Doug Hellmann]

$ tox -e venv -- sphinx-build doc/source doc/build
GLOB sdist-make: /home/vagrant/repos/openstack/oslo.messaging/setup.py
venv inst-nodeps: /home/vagrant/repos/openstack/oslo.messaging/.tox/dist/oslo.messaging-1.3.0a7.33.ga75cc84.zip
venv runtests: commands[0] | sphinx-build doc/source doc/build
Running Sphinx v1.2b3
loading pickled environment... done
No builder selected, using default: html
Using openstack theme from /home/vagrant/repos/openstack/oslo.messaging/.tox/venv/local/lib/python2.7/site-packages/oslosphinx/theme
building [html]: targets for 10 source files that are out of date
updating environment: 0 added, 10 changed, 0 removed
reading sources... [100%] transport
/home/vagrant/repos/openstack/oslo.messaging/doc/source/index.rst:10: WARNING: toctree contains reference to nonexisting document u'opts'
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/server.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.start, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/server.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.stop, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/server.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.wait, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/server.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.get_local_context, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/server.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/notification_listener.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.start, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/notification_listener.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.stop, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/notification_listener.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.MessageHandlingServer.wait, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/notification_listener.rst, use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of oslo.messaging.get_local_context, other instance in /home/vagrant/repos/openstack/oslo.messaging/doc/source/notification_listener.rst, use :noindex: for one of them
/home/vagrant/repos/openstack/oslo.messaging/.tox/venv/local/lib/python2.7/site-packages/oslo/messaging/transport.py:docstring of oslo.messaging.TransportURL.parse:20: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/vagrant/repos/openstack/oslo.messaging/.tox/venv/local/lib/python2.7/site-packages/oslo/messaging/transport.py:docstring of oslo.messaging.TransportURL.parse:31: WARNING: Definition list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] transport
writing additional files... genindex py-modindex search
copying static files... WARNING: html_static_path entry u'/home/vagrant/repos/openstack/oslo.messaging/doc/source/static' does not exist
done
copying extra files... dumping search index... done
dumping object inventory... done
build succeeded, 14 warnings.
__________________________________________________ summary ___________________________________________________
  venv: commands succeeded
  congratulations :)

[Doug Hellmann (doug-hellmann)]

After we fix them, we should turn on the sphinx setting that causes an error when we have a warning, so we don't add new ones.

[Derek Anderson (derek-anderson)]

Taking this on as part of Openstack upstream training.

[Derek Anderson (derek-anderson)]

It looks like this documentation was only partially updated after the local context lib was added in f1612f28954e3 .

Breaking out the local_context docs into their own reference and cleaning them out of the server and notoification_listener docs would be the best choice.

There may be other places where we have disorganized, and I'll do some more research and follow up.

[Mehdi Abaakouk (sileht)]

This looks fixed:

 $ tox -e venv -- sphinx-build doc/source doc/build
GLOB sdist-make: /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/setup.py
venv recreate: /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/.tox/venv
venv installdeps: -r/home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/requirements.txt, -r/home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/test-requirements.txt
venv inst: /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/.tox/dist/oslo.messaging-1.5.0.1.g554ad9d.zip
venv runtests: PYTHONHASHSEED='1424186883'
venv runtests: commands[0] | sphinx-build doc/source doc/build
Running Sphinx v1.2.3
loading pickled environment... not yet created
No builder selected, using default: html
Using openstack theme from /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/.tox/venv/local/lib/python2.7/site-packages/oslosphinx/theme
building [html]: targets for 13 source files that are out of date
updating environment: 13 added, 0 changed, 0 removed
reading sources... [100%] transport
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] transport
writing additional files... genindex py-modindex search
copying static files... WARNING: html_static_path entry u'/home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/doc/source/static' does not exist
done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.
___________________________________________________________________ summary ____________________________________________________________________
  venv: commands succeeded
  congratulations :)

tox -e venv -- sphinx-build doc/source doc/build 18.23s user 2.88s system 80% cpu 26.260 total

 $ tox -e docs
GLOB sdist-make: /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/setup.py
docs inst-nodeps: /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/.tox/dist/oslo.messaging-1.5.0.1.g554ad9d.zip
docs runtests: PYTHONHASHSEED='4120661581'
docs runtests: commands[0] | python setup.py build_sphinx
running build_sphinx
Running Sphinx v1.2.3
loading pickled environment... done
Using openstack theme from /home/sileht/workspace/eNovance/os_dev/stack-master/oslo.messaging/.tox/docs/local/lib/python2.7/site-packages/oslosphinx/theme
building [html]: all source files
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] transport
writing additional files... genindex py-modindex search
copying static files... WARNING: html_static_path entry u'/home/sileht/workspace/eNovance/os_dev/stack-master/...

[Doug Hellmann (doug-hellmann)]

https://review.openstack.org/139201

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/139201
Committed: https://git.openstack.org/cgit/openstack/oslo.messaging/commit/?id=bf4ab5a9e4fc21220a82788bcf6237bcdeae8ec7
Submitter: Jenkins
Branch: master

commit bf4ab5a9e4fc21220a82788bcf6237bcdeae8ec7
Author: Doug Hellmann <email address hidden>
Date: Thu Dec 4 16:13:17 2014 -0500

    Treat sphinx warnings as errors

    Closes-Bug: #1287415

    Change-Id: I43f406a8608724ac55c9ae6aea847d75594ba6f6