Deprecate config value: source_parsers

6 files changed, 59 insertions, 6 deletions

diff --git a/CHANGES b/CHANGES
index 3a5131e7b..695430673 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 830fb69a0..5af846ee7 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 db4122b16..8a5d2f60d 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -92,6 +92,7 @@ builtin_extensions = (
     '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 @@ class Sphinx(object):
 
     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 e28e0f916..cd6e1ae2a 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 e48c12f96..3d7784d47 100644
--- a/sphinx/registry.py
+++ b/sphinx/registry.py
@@ -13,7 +13,7 @@ from __future__ import print_function
 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.locale import __
 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 @@ class SphinxComponentRegistry(object):
         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 000000000..edd8cac61
--- /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,
+    }