diff --git a/CHANGES b/CHANGES index 3a5131e7bd2..69543067342 100644 --- a/CHANGES +++ b/CHANGES @@ -10,6 +10,9 @@ Incompatible changes Deprecated ---------- +* :confval:`source_parsers` is deprecated. Please use ``add_source_parser()`` + instead. + Features added -------------- diff --git a/doc/config.rst b/doc/config.rst index 830fb69a013..5af846ee761 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -123,6 +123,10 @@ General configuration .. versionadded:: 1.3 + .. deprecated:: 1.8 + Now Sphinx provides an API :meth:`Sphinx.add_source_parser` to register + a source parser. Please use it instead. + .. confval:: master_doc The document name of the "master" document, that is, the document that diff --git a/sphinx/application.py b/sphinx/application.py index db4122b1625..8a5d2f60dde 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -92,6 +92,7 @@ 'sphinx.roles', 'sphinx.transforms.post_transforms', 'sphinx.transforms.post_transforms.images', + 'sphinx.util.compat', # collectors should be loaded by specific order 'sphinx.environment.collectors.dependencies', 'sphinx.environment.collectors.asset', @@ -287,8 +288,6 @@ def _init_i18n(self): def _init_source_parsers(self): # type: () -> None - for suffix, parser in iteritems(self.config.source_parsers): - self.add_source_parser(suffix, parser) for suffix, parser in iteritems(self.registry.get_source_parsers()): if suffix not in self.config.source_suffix and suffix != '*': self.config.source_suffix.append(suffix) diff --git a/sphinx/deprecation.py b/sphinx/deprecation.py index e28e0f9162b..cd6e1ae2a33 100644 --- a/sphinx/deprecation.py +++ b/sphinx/deprecation.py @@ -22,4 +22,8 @@ class RemovedInSphinx20Warning(PendingDeprecationWarning): pass +class RemovedInSphinx30Warning(PendingDeprecationWarning): + pass + + RemovedInNextVersionWarning = RemovedInSphinx18Warning diff --git a/sphinx/registry.py b/sphinx/registry.py index e48c12f9636..3d7784d471d 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -13,7 +13,7 @@ import traceback from pkg_resources import iter_entry_points -from six import iteritems, itervalues, string_types +from six import iteritems, itervalues from sphinx.errors import ExtensionError, SphinxError, VersionRequirementError from sphinx.extension import Extension @@ -23,7 +23,6 @@ from sphinx.parsers import Parser as SphinxParser from sphinx.roles import XRefRole from sphinx.util import logging -from sphinx.util import import_object from sphinx.util.console import bold # type: ignore from sphinx.util.docutils import directive_helper @@ -216,8 +215,6 @@ def get_source_parser(self, filename): if parser_class is None: raise SphinxError(__('Source parser for %s not registered') % filename) else: - if isinstance(parser_class, string_types): - parser_class = import_object(parser_class, 'source parser') # type: ignore return parser_class def get_source_parsers(self): diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py new file mode 100644 index 00000000000..edd8cac616d --- /dev/null +++ b/sphinx/util/compat.py @@ -0,0 +1,46 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.compat + ~~~~~~~~~~~~~~~~~~ + + modules for backward compatibility + + :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import warnings + +from six import string_types, iteritems + +from sphinx.deprecation import RemovedInSphinx30Warning +from sphinx.util import import_object + +if False: + # For type annotation + from typing import Any, Dict # NOQA + from sphinx.application import Sphinx # NOQA + from sphinx.config import Config # NOQA + + +def deprecate_source_parsers(app, config): + # type: (Sphinx, Config) -> None + if config.source_parsers: + warnings.warn('The config variable "source_parsers" is deprecated. ' + 'Please use app.add_source_parser() API instead.', + RemovedInSphinx30Warning) + for suffix, parser in iteritems(config.source_parsers): + if isinstance(parser, string_types): + parser = import_object(parser, 'source parser') # type: ignore + app.add_source_parser(suffix, parser) + + +def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] + app.connect('config-inited', deprecate_source_parsers) + + return { + 'version': 'builtin', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + }