Deprecate config value: source_parsers

CHANGES

@@ -10,6 +10,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* :confval:`source_parsers` is deprecated. Please use ``add_source_parser()``
+  instead.
+
 Features added
 --------------
 

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

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)

sphinx/deprecation.py

@@ -22,4 +22,8 @@ class RemovedInSphinx20Warning(PendingDeprecationWarning):
     pass
 
 
+class RemovedInSphinx30Warning(PendingDeprecationWarning):
+    pass
+
+
 RemovedInNextVersionWarning = RemovedInSphinx18Warning

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

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,
+    }