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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev