Open Stack

tl;dr
-----

A few project that use wsme.sphinxext or some other extensions that
register similar directives multiple times have been unable to turn on
the warning-is-error flag as part of the doc migration. The solution to
that problem is to add some warning suppression information to the local
sphinx build. See [1] for an example.

Why am I seeing the warning "directive 'foo' is already registered, it
will be overridden"?
----------------------------------------------------------------------

Our doc build jobs invoke sphinx through pbr by running "tox -e venv --
python setup.py build_sphinx". Doing that, instead of sphinx-build, has
allowed us to set several sphinx configuration options consistently
across all projects without having to land a patch in every repository.
One of those options was to suppress warnings like this, which are
informational but don't actually cause us any problems.

When we updated to Sphinx 1.6.2, the integration in pbr changed in a way
that makes it impossible to pass those options through. That means we
are no longer suppressing the warnings globally. When the
warning-is-error flag is turned on, the informational warning turns into
an error and the build fails.

How do I eliminate the warning?
-------------------------------

To suppress the warning, set the "suppress_warnings" option in
doc/source/conf.py to the list of names of warnings to be suppressed. By
default the list is empty. You do not want to suppress *all* warnings,
because that would make the warning-is-error flag irrelevant. It is
safe, however, to suppress warnings related to things that extensions
do, like registering directives and roles. This is what pbr used to do.

For example, in [1] I have set the option to:

	suppress_warnings = [
		'app.add_directive', 'app.add_role',
		'app.add_generic_role', 'app.add_node',
		'image.nonlocal_uri',
	]

This ignores warnings related to extension actions, over which you have
no control, and tells Sphinx that it is OK to refer to images that are
not in the local repository.

Again, please be conservative about adding things to this list. Consider
it like disabling a rule in a code linter.

Doug

[1] https://review.openstack.org/#/c/483953/1/doc/source/conf.py
[2] http://www.sphinx-doc.org/en/stable/config.html?highlight=suppress_warnings#confval-suppress_warnings