From bfd71cd77bd72e339a90781fae4d05f9c349c748 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 15 Jul 2017 19:27:04 +0900 Subject: [PATCH 1/6] Fix #3926: Add ``autodoc_warningiserror`` to suppress the behavior of ``-W`` option --- CHANGES | 3 +++ doc/ext/autodoc.rst | 7 +++++++ sphinx/ext/autodoc.py | 4 +++- sphinx/util/logging.py | 35 ++++++++++++++++++++++++++++++++++- tests/test_util_logging.py | 24 ++++++++++++++++++++++++ 5 files changed, 71 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 3ff50f28b..c6c19e7a3 100644 --- a/CHANGES +++ b/CHANGES @@ -13,6 +13,9 @@ Deprecated Features added -------------- +* #3926: Add ``autodoc_warningiserror`` to suppress the behavior of ``-W`` + option during importing target modules on autodoc + Bugs fixed ---------- diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 62079c928..1f1892dbf 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -386,6 +386,13 @@ There are also new config values that you can set: This config value only requires to declare the top-level modules that should be mocked. +.. confval:: autodoc_warningiserror + + This value controls the behavior of :option:`sphinx-build -W` during + importing modules. + If ``False`` is given, autodoc forcely suppresses the error if the imported + module emits warnings. By default, ``True``. + Docstring preprocessing ----------------------- diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 4af2bb3c6..91feb6a2a 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -654,7 +654,8 @@ class Documenter(object): logger.debug('[autodoc] import %s', self.modname) with warnings.catch_warnings(): warnings.filterwarnings("ignore", category=ImportWarning) - __import__(self.modname) + with logging.skip_warningiserror(not self.env.config.autodoc_warningiserror): + __import__(self.modname) parent = None obj = self.module = sys.modules[self.modname] logger.debug('[autodoc] => %r', obj) @@ -1883,6 +1884,7 @@ def setup(app): app.add_config_value('autodoc_default_flags', [], True) app.add_config_value('autodoc_docstring_signature', True, True) app.add_config_value('autodoc_mock_imports', [], True) + app.add_config_value('autodoc_warningiserror', True, True) app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 85766a774..04cb5fcab 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -249,6 +249,27 @@ def pending_logging(): memhandler.flushTo(logger) +@contextmanager +def skip_warningiserror(skip=True): + # type: (bool) -> Generator + """contextmanager to skip WarningIsErrorFilter for a while.""" + logger = logging.getLogger() + + if skip is False: + yield + else: + try: + disabler = DisableWarningIsErrorFilter() + for handler in logger.handlers: + # use internal method; filters.insert() directly to install disabler + # before WarningIsErrorFilter + handler.filters.insert(0, disabler) + yield + finally: + for handler in logger.handlers: + handler.removeFilter(disabler) + + class LogCollector(object): def __init__(self): # type: () -> None @@ -330,7 +351,10 @@ class WarningIsErrorFilter(logging.Filter): def filter(self, record): # type: (logging.LogRecord) -> bool - if self.app.warningiserror: + if getattr(record, 'skip_warningsiserror', False): + # disabled by DisableWarningIsErrorFilter + return True + elif self.app.warningiserror: location = getattr(record, 'location', '') if location: raise SphinxWarning(location + ":" + record.msg % record.args) @@ -340,6 +364,15 @@ class WarningIsErrorFilter(logging.Filter): return True +class DisableWarningIsErrorFilter(logging.Filter): + """Disable WarningIsErrorFilter if this filter installed.""" + + def filter(self, record): + # type: (logging.LogRecord) -> bool + record.skip_warningsiserror = True # type: ignore + return True + + class WarningLogRecordTranslator(logging.Filter): """Converts a log record to one Sphinx expects diff --git a/tests/test_util_logging.py b/tests/test_util_logging.py index 7ca7bd655..717aa6cd4 100644 --- a/tests/test_util_logging.py +++ b/tests/test_util_logging.py @@ -272,3 +272,27 @@ def test_output_with_unencodable_char(app, status, warning): status.seek(0) logger.info(u"unicode \u206d...") assert status.getvalue() == "unicode ?...\n" + + +def test_skip_warningiserror(app, status, warning): + logging.setup(app, status, warning) + logger = logging.getLogger(__name__) + + app.warningiserror = True + with logging.skip_warningiserror(): + logger.warning('message') + + # if False, warning raises SphinxWarning exception + with pytest.raises(SphinxWarning): + with logging.skip_warningiserror(False): + logger.warning('message') + + # It also works during pending_warnings. + with logging.pending_warnings(): + with logging.skip_warningiserror(): + logger.warning('message') + + with pytest.raises(SphinxWarning): + with logging.pending_warnings(): + with logging.skip_warningiserror(False): + logger.warning('message') From 1869f4d674f543747972d740a386f7165f414379 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 16 Jul 2017 01:48:09 +0900 Subject: [PATCH 2/6] Update docs (refs: #3923) --- doc/extdev/appapi.rst | 22 ++++++++++++++++++++++ doc/extdev/envapi.rst | 4 ---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index a27340d55..ce856d031 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -454,6 +454,28 @@ The application object also provides support for emitting leveled messages. .. automethod:: Sphinx.debug2 +Sphinx runtime information +-------------------------- + +The application object also provides runtime information as attributes. + +.. attribute:: srcdir + + Source directory. + +.. attribute:: confdir + + Directory containing ``conf.py``. + +.. attribute:: doctreedir + + Directory for storing pickled doctrees. + +.. attribute:: outdir + + Directory for storing built document. + + .. _events: Sphinx core events diff --git a/doc/extdev/envapi.rst b/doc/extdev/envapi.rst index 729725fc5..442cfde15 100644 --- a/doc/extdev/envapi.rst +++ b/doc/extdev/envapi.rst @@ -19,10 +19,6 @@ Build environment API Source directory. - .. attribute:: confdir - - Directory containing ``conf.py``. - .. attribute:: doctreedir Directory for storing pickled doctrees. From 5ce51728ba5ea9a4a2bf5d6093a49d1c022c3c1c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 16 Jul 2017 11:47:39 +0900 Subject: [PATCH 3/6] Fix #3924: docname lost after dynamically parsing RST in extension --- CHANGES | 2 ++ sphinx/environment/__init__.py | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index c6c19e7a3..5a8891e97 100644 --- a/CHANGES +++ b/CHANGES @@ -19,6 +19,8 @@ Features added Bugs fixed ---------- +* #3924: docname lost after dynamically parsing RST in extension + Testing -------- diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index 70fdbaeca..edec9ba2f 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -18,6 +18,7 @@ import codecs import fnmatch import warnings from os import path +from copy import copy from collections import defaultdict from six import BytesIO, itervalues, class_types, next @@ -946,6 +947,7 @@ class BuildEnvironment(object): """Apply all post-transforms.""" try: # set env.docname during applying post-transforms + backup = copy(self.temp_data) self.temp_data['docname'] = docname transformer = SphinxTransformer(doctree) @@ -953,7 +955,7 @@ class BuildEnvironment(object): transformer.add_transforms(self.app.post_transforms) transformer.apply_transforms() finally: - self.temp_data.clear() + self.temp_data = backup # allow custom references to be resolved self.app.emit('doctree-resolved', doctree, docname) From 621eca38bec307a0b33e3c5c837906a11eabf4f0 Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 24 Jul 2017 14:51:06 +0200 Subject: [PATCH 4/6] Fix #3946 (typo in sphinx.sty) --- sphinx/texinputs/sphinx.sty | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 09d77949d..2eafd1803 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -1135,7 +1135,7 @@ % and there is consequently no corresponding package option \definecolor{sphinxnoteBgColor}{rgb}{1,1,1} \definecolor{sphinxhintBgColor}{rgb}{1,1,1} -\definecolor{sphinimportantBgColor}{rgb}{1,1,1} +\definecolor{sphinximportantBgColor}{rgb}{1,1,1} \definecolor{sphinxtipBgColor}{rgb}{1,1,1} % Others get more distinction From 7f9907be61af6d6386c27b131a3a6e4e816cf42b Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 24 Jul 2017 15:08:34 +0200 Subject: [PATCH 5/6] Update CHANGES --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index 5a8891e97..4d037ed60 100644 --- a/CHANGES +++ b/CHANGES @@ -20,6 +20,7 @@ Bugs fixed ---------- * #3924: docname lost after dynamically parsing RST in extension +* #3946: Typo in sphinx.sty (this was a bug with no effect in default context) Testing -------- From f353bc63d780277026c05a70d75be271fcfa13fe Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 24 Jul 2017 15:15:52 +0200 Subject: [PATCH 6/6] Update LaTeX style file version date --- sphinx/texinputs/sphinx.sty | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 2eafd1803..a28220cbc 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,7 +6,7 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2017/06/17 v1.6.3 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2017/07/24 v1.6.4 LaTeX package (Sphinx markup)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but