Merge pull request #4465 from tk0miya/improve_config

Improve config

CHANGES

@@ -13,6 +13,10 @@ Deprecated
 Features added
 --------------
 
+* Add :event:`config-inited` event
+* Add ``sphinx.config.Any`` to represent the config value accepts any type of
+  value
+
 Bugs fixed
 ----------
 

doc/extdev/appapi.rst

@@ -500,6 +500,12 @@ handlers to the events.  Example:
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: config-inited (app, config)
+
+   Emitted when the config object has been initialized.
+
+   .. versionadded:: 1.8
+
 .. event:: env-get-outdated (app, env, added, changed, removed)
 
    Emitted when the environment determines which source files have changed and

sphinx/application.py

@@ -76,6 +76,7 @@ builtin_extensions = (
     'sphinx.builders.text',
     'sphinx.builders.websupport',
     'sphinx.builders.xml',
+    'sphinx.config',
     'sphinx.domains.c',
     'sphinx.domains.cpp',
     'sphinx.domains.javascript',
@@ -228,6 +229,7 @@ class Sphinx(object):
 
         # now that we know all config values, collect them from conf.py
         self.config.init_values()
+        self.emit('config-inited', self.config)
 
         # check extension versions if requested
         verify_required_extensions(self, self.config.needs_extensions)

sphinx/builders/latex.py

@@ -262,9 +262,9 @@ class LaTeXBuilder(Builder):
                                    path.join(self.srcdir, src), err)
 
 
-def validate_config_values(app):
-    # type: (Sphinx) -> None
-    for document in app.config.latex_documents:
+def validate_config_values(app, config):
+    # type: (Sphinx, Config) -> None
+    for document in config.latex_documents:
         try:
             text_type(document[2])
         except UnicodeDecodeError:
@@ -304,7 +304,7 @@ def default_latex_docclass(config):
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
     app.add_builder(LaTeXBuilder)
-    app.connect('builder-inited', validate_config_values)
+    app.connect('config-inited', validate_config_values)
 
     app.add_config_value('latex_engine', default_latex_engine, None,
                          ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))

sphinx/config.py

@@ -26,6 +26,7 @@ from sphinx.util.pycompat import execfile_, NoneType
 if False:
     # For type annotation
     from typing import Any, Callable, Dict, Iterable, Iterator, List, Tuple, Union  # NOQA
+    from sphinx.application import Sphinx  # NOQA
     from sphinx.util.tags import Tags  # NOQA
 
 logger = logging.getLogger(__name__)
@@ -54,6 +55,10 @@ ConfigValue = NamedTuple('ConfigValue', [('name', str),
                                          ('rebuild', Union[bool, unicode])])
 
 
+#: represents the config value accepts any type of value.
+Any = object()
+
+
 class ENUM(object):
     """represents the config value should be a one of candidates.
 
@@ -109,7 +114,7 @@ class Config(object):
         figure_language_filename = (u'{root}.{language}{ext}', 'env', [str]),
 
         master_doc = ('contents', 'env'),
-        source_suffix = (['.rst'], 'env'),
+        source_suffix = (['.rst'], 'env', Any),
         source_encoding = ('utf-8-sig', 'env'),
         source_parsers = ({}, 'env'),
         exclude_patterns = ([], 'env'),
@@ -212,7 +217,10 @@ class Config(object):
             if default is None and not permitted:
                 continue  # neither inferrable nor expliclitly permitted types
             current = self[name]
-            if isinstance(permitted, ENUM):
+            if permitted is Any:
+                # any type of value is accepted
+                pass
+            elif isinstance(permitted, ENUM):
                 if not permitted.match(current):
                     logger.warning(CONFIG_ENUM_WARNING.format(
                         name=name, current=current, candidates=permitted.candidates))
@@ -309,8 +317,6 @@ class Config(object):
         for name in config:
             if name in self.values:
                 self.__dict__[name] = config[name]  # type: ignore
-        if isinstance(self.source_suffix, string_types):  # type: ignore
-            self.source_suffix = [self.source_suffix]  # type: ignore
 
     def __getattr__(self, name):
         # type: (unicode) -> Any
@@ -351,3 +357,21 @@ class Config(object):
     def filter(self, rebuild):
         # type: (str) -> Iterator[ConfigValue]
         return (value for value in self if value.rebuild == rebuild)  # type: ignore
+
+
+def convert_source_suffix(app, config):
+    # type: (Sphinx, Config) -> None
+    """This converts source_suffix to string-list."""
+    if isinstance(config.source_suffix, string_types):
+        config.source_suffix = [config.source_suffix]  # type: ignore
+
+
+def setup(app):
+    # type: (Sphinx) -> Dict[unicode, Any]
+    app.connect('config-inited', convert_source_suffix)
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinx/events.py

@@ -27,6 +27,7 @@ if False:
 # List of all known core events. Maps name to arguments description.
 core_events = {
     'builder-inited': '',
+    'config-inited': 'config',
     'env-get-outdated': 'env, added, changed, removed',
     'env-get-updated': 'env',
     'env-purge-doc': 'env, docname',