sphinx-doc / sphinx-doc/sphinx

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

Open
#9,142 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api help wanted type:proposal
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the behavior with the conf.py and index.rst examples using the shown sphinx-build command, comparing warnings.warn with the Sphinx logger warning. Read Sphinx's warning and logging handling to determine where third-party warnings are processed. Done means the example's -W build fails when the extension emits warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.