sphinx-build -W should make third-party extension warnings cause build failure
#9,142 opened on 2021年4月28日
Repository metrics
- Stars
- (5,625 stars)
- PR merge metrics
- (平均マージ 10d 11h) (30d で 11 merged PRs)
説明
Describe the bug
If a third-party extension module emits a warning, this does not cause a failure on a -W build.
To Reproduce Steps to reproduce the behavior:
$ cat conf.py
import warnings
from sphinx.util.logging import getLogger
from docutils.parsers.rst import Directive
class FooDirective(Directive):
def run(self):
warnings.warn("foo")
# getLogger("fooext").warning("foo")
return []
def setup(app):
app.add_directive("foo", FooDirective)
$ cat index.rst
.. foo::
$ sphinx-build -b html -d _build/doctrees . _build/html -W
Expected behavior Build failure.
Your project Create conf.py and index.rst as above.
Environment info
- OS: fedora33
- Python version: 3.9.1
- Sphinx version: 3.5.0
- Sphinx extensions: none
- Extra tools: none
Additional context
I realize that emitting the logging via sphinx.util.logging.getLogger("myext").warning "fixes" the problem (cf commented-out line in the example above), but sometimes the third-party extension itself wants to run user-provided (fourth-party?) code -- an example is Matplotlib's plot_directive (https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html), which creates and embeds plots in docs, and is seems unreasonable to request fourth-party code to use a sphinx logger (especially as that code may be intended to also work as a standalone script).
plot_directive could perhaps wrap the fourth-party code in warnings.catch_warnings and then translate those to logging calls, but that seems like the kind of feature that sphinx could perhaps provide? (something like with sphinx.util.logging.transfer_warnings_to_sphinx_logging(): ..., perhaps with a better name :-)).