sphinx-doc/sphinx

sphinx-build -W should make third-party extension warnings cause build failure

Open

#9,142 opened on 2021年4月28日

GitHub で見る
 (4 comments) (0 reactions) (0 assignees)Python (1,985 forks)batch import
apihelp wantedtype:proposal

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 :-)).

コントリビューターガイド