sphinx-build -W should make third-party extension warnings cause build failure
#9,142 创建于 2021年4月28日
仓库指标
- Star
- (5,625 star)
- PR 合并指标
- (平均合并 10天 11小时) (30 天内合并 11 个 PR)
描述
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 :-)).