"""Build configuration file handling.""" from __future__ import annotations import time import traceback import types import warnings from contextlib import chdir from os import getenv from pathlib import Path from typing import TYPE_CHECKING, Any, Literal, NamedTuple from sphinx.deprecation import RemovedInSphinx90Warning from sphinx.errors import ConfigError, ExtensionError from sphinx.locale import _, __ from sphinx.util import logging if TYPE_CHECKING: import os from collections.abc import Collection, Iterable, Iterator, Sequence, Set from typing import TypeAlias from sphinx.application import Sphinx from sphinx.environment import BuildEnvironment from sphinx.util.tags import Tags from sphinx.util.typing import ExtensionMetadata, _ExtensionSetupFunc logger = logging.getLogger(__name__) _ConfigRebuild: TypeAlias = Literal[ '', 'env', 'epub', 'gettext', 'html', # sphinxcontrib-applehelp 'applehelp', # sphinxcontrib-devhelp 'devhelp', ] CONFIG_FILENAME = 'conf.py' UNSERIALIZABLE_TYPES = (type, types.ModuleType, types.FunctionType) class ConfigValue(NamedTuple): name: str value: Any rebuild: _ConfigRebuild def is_serializable(obj: object, *, _seen: frozenset[int] = frozenset()) -> bool: """Check if an object is serializable or not.""" if isinstance(obj, UNSERIALIZABLE_TYPES): return False # use id() to handle un-hashable objects if id(obj) in _seen: return True if isinstance(obj, dict): seen = _seen | {id(obj)} return all( is_serializable(key, _seen=seen) and is_serializable(value, _seen=seen) for key, value in obj.items() ) elif isinstance(obj, list | tuple | set | frozenset): seen = _seen | {id(obj)} return all(is_serializable(item, _seen=seen) for item in obj) # if an issue occurs for a non-serializable type, pickle will complain # since the object is likely coming from a third-party extension # (we natively expect 'simple' types and not weird ones) return True class ENUM: """Represents the candidates which a config value should be one of. Example: app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline')) """ def __init__(self, *candidates: str | bool | None) -> None: self._candidates = frozenset(candidates) def __repr__(self) -> str: return f'ENUM({", ".join(sorted(map(repr, self._candidates)))})' def match(self, value: str | bool | None | Sequence[str | bool | None]) -> bool: # NoQA: RUF036 if isinstance(value, str | bool | None): return value in self._candidates return all(item in self._candidates for item in value) _OptValidTypes: TypeAlias = frozenset[type] | ENUM class _Opt: __slots__ = 'default', 'rebuild', 'valid_types', 'description' default: Any rebuild: _ConfigRebuild valid_types: _OptValidTypes description: str def __init__( self, default: Any, rebuild: _ConfigRebuild, valid_types: _OptValidTypes, description: str = '', ) -> None: """Configuration option type for Sphinx. The type is intended to be immutable; changing the field values is an unsupported action. No validation is performed on the values, though consumers will likely expect them to be of the types advertised. The old tuple-based interface will be removed in Sphinx 9. """ super().__setattr__('default', default) super().__setattr__('rebuild', rebuild) super().__setattr__('valid_types', valid_types) super().__setattr__('description', description) def __repr__(self) -> str: return ( f'{self.__class__.__qualname__}(' f'default={self.default!r}, ' f'rebuild={self.rebuild!r}, ' f'valid_types={self.rebuild!r}, ' f'description={self.description!r})' ) def __eq__(self, other: object) -> bool: if isinstance(other, _Opt): self_tpl = ( self.default, self.rebuild, self.valid_types, self.description, ) other_tpl = ( other.default, other.rebuild, other.valid_types, other.description, ) return self_tpl == other_tpl return NotImplemented def __lt__(self, other: _Opt) -> bool: if self.__class__ is other.__class__: self_tpl = ( self.default, self.rebuild, self.valid_types, self.description, ) other_tpl = ( other.default, other.rebuild, other.valid_types, other.description, ) return self_tpl > other_tpl return NotImplemented def __hash__(self) -> int: return hash((self.default, self.rebuild, self.valid_types, self.description)) def __setattr__(self, key: str, value: Any) -> None: if key in {'default', 'rebuild', 'valid_types', 'description'}: msg = f'{self.__class__.__name__!r} object does not support assignment to {key!r}' raise TypeError(msg) super().__setattr__(key, value) def __delattr__(self, key: str) -> None: if key in {'default', 'rebuild', 'valid_types', 'description'}: msg = f'{self.__class__.__name__!r} object does not support deletion of {key!r}' raise TypeError(msg) super().__delattr__(key) def __getstate__(self) -> tuple[Any, _ConfigRebuild, _OptValidTypes, str]: return self.default, self.rebuild, self.valid_types, self.description def __setstate__( self, state: tuple[Any, _ConfigRebuild, _OptValidTypes, str] ) -> None: default, rebuild, valid_types, description = state super().__setattr__('default', default) super().__setattr__('rebuild', rebuild) super().__setattr__('valid_types', valid_types) super().__setattr__('description', description) def __getitem__(self, item: int | slice) -> Any: warnings.warn( f'The {self.__class__.__name__!r} object tuple interface is deprecated, ' "use attribute access instead for 'default', 'rebuild', and 'valid_types'.", RemovedInSphinx90Warning, stacklevel=2, ) return (self.default, self.rebuild, self.valid_types)[item] class Config: r"""Configuration file abstraction. The Config object makes the values of all config options available as attributes. It is exposed via the :py:class:`~sphinx.application.Sphinx`\ ``.config`` and :py:class:`sphinx.environment.BuildEnvironment`\ ``.config`` attributes. For example, to get the value of :confval:`language`, use either ``app.config.language`` or ``env.config.language``. """ # The values are: # 1. Default # 2. What needs to be rebuilt if changed # 3. Valid types # If you add a value here, remember to include it in the docs! config_values: dict[str, _Opt] = { # general options 'project': _Opt('Project name not set', 'env', frozenset((str,))), 'author': _Opt('Author name not set', 'env', frozenset((str,))), 'project_copyright': _Opt('', 'html', frozenset((str, tuple, list))), 'copyright': _Opt( lambda config: config.project_copyright, 'html', frozenset((str, tuple, list)), ), 'version': _Opt('', 'env', frozenset((str,))), 'release': _Opt('', 'env', frozenset((str,))), 'today': _Opt('', 'env', frozenset((str,))), # the real default is locale-dependent 'today_fmt': _Opt(None, 'env', frozenset((str,))), 'language': _Opt('en', 'env', frozenset((str,))), 'locale_dirs': _Opt(['locales'], 'env', frozenset((list, tuple))), 'figure_language_filename': _Opt( '{root}.{language}{ext}', 'env', frozenset((str,)) ), 'gettext_allow_fuzzy_translations': _Opt(False, 'gettext', frozenset((bool,))), 'translation_progress_classes': _Opt( False, 'env', ENUM(True, False, 'translated', 'untranslated') ), 'master_doc': _Opt('index', 'env', frozenset((str,))), 'root_doc': _Opt(lambda config: config.master_doc, 'env', frozenset((str,))), # ``source_suffix`` type is actually ``dict[str, str | None]``: # see ``convert_source_suffix()`` below. 'source_suffix': _Opt({'.rst': 'restructuredtext'}, 'env', Any), # type: ignore[arg-type] 'source_encoding': _Opt('utf-8-sig', 'env', frozenset((str,))), 'exclude_patterns': _Opt([], 'env', frozenset((str,))), 'include_patterns': _Opt(['**'], 'env', frozenset((str,))), 'default_role': _Opt(None, 'env', frozenset((str,))), 'add_function_parentheses': _Opt(True, 'env', frozenset((bool,))), 'add_module_names': _Opt(True, 'env', frozenset((bool,))), 'toc_object_entries': _Opt(True, 'env', frozenset((bool,))), 'toc_object_entries_show_parents': _Opt( 'domain', 'env', ENUM('domain', 'all', 'hide') ), 'trim_footnote_reference_space': _Opt(False, 'env', frozenset((bool,))), 'show_authors': _Opt(False, 'env', frozenset((bool,))), 'pygments_style': _Opt(None, 'html', frozenset((str,))), 'highlight_language': _Opt('default', 'env', frozenset((str,))), 'highlight_options': _Opt({}, 'env', frozenset((dict,))), 'templates_path': _Opt([], 'html', frozenset((list,))), 'template_bridge': _Opt(None, 'html', frozenset((str,))), 'keep_warnings': _Opt(False, 'env', frozenset((bool,))), 'suppress_warnings': _Opt([], 'env', frozenset((list, tuple))), 'show_warning_types': _Opt(True, 'env', frozenset((bool,))), 'modindex_common_prefix': _Opt([], 'html', frozenset((list, tuple))), 'rst_epilog': _Opt(None, 'env', frozenset((str,))), 'rst_prolog': _Opt(None, 'env', frozenset((str,))), 'trim_doctest_flags': _Opt(True, 'env', frozenset((bool,))), 'primary_domain': _Opt('py', 'env', frozenset((types.NoneType,))), 'needs_sphinx': _Opt(None, '', frozenset((str,))), 'needs_extensions': _Opt({}, '', frozenset((dict,))), 'manpages_url': _Opt(None, 'env', frozenset((str, types.NoneType))), 'nitpicky': _Opt(False, '', frozenset((bool,))), 'nitpick_ignore': _Opt([], '', frozenset((set, list, tuple))), 'nitpick_ignore_regex': _Opt([], '', frozenset((set, list, tuple))), 'numfig': _Opt(False, 'env', frozenset((bool,))), 'numfig_secnum_depth': _Opt(1, 'env', frozenset((int, types.NoneType))), # numfig_format will be initialized in init_numfig_format() 'numfig_format': _Opt({}, 'env', frozenset((dict,))), 'maximum_signature_line_length': _Opt( None, 'env', frozenset((int, types.NoneType)) ), 'math_number_all': _Opt(False, 'env', frozenset((bool,))), 'math_eqref_format': _Opt(None, 'env', frozenset((str,))), 'math_numfig': _Opt(True, 'env', frozenset((bool,))), 'math_numsep': _Opt('.', 'env', frozenset((str,))), 'tls_verify': _Opt(True, 'env', frozenset((bool,))), 'tls_cacerts': _Opt(None, 'env', frozenset((str, dict, types.NoneType))), 'user_agent': _Opt(None, 'env', frozenset((str,))), 'smartquotes': _Opt(True, 'env', frozenset((bool,))), 'smartquotes_action': _Opt('qDe', 'env', frozenset((str,))), 'smartquotes_excludes': _Opt( {'languages': ['ja', 'zh_CN', 'zh_TW'], 'builders': ['man', 'text']}, 'env', frozenset((dict,)), ), 'option_emphasise_placeholders': _Opt(False, 'env', frozenset((bool,))), } def __init__( self, config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None, ) -> None: raw_config: dict[str, Any] = config or {} self._overrides = dict(overrides) if overrides is not None else {} self._options = Config.config_values.copy() self._raw_config = raw_config for name in list(self._overrides.keys()): if '.' in name: real_name, key = name.split('.', 1) raw_config.setdefault(real_name, {})[key] = self._overrides.pop(name) self.setup: _ExtensionSetupFunc | None = raw_config.get('setup') if 'extensions' in self._overrides: extensions = self._overrides.pop('extensions') if isinstance(extensions, str): raw_config['extensions'] = extensions.split(',') else: raw_config['extensions'] = extensions self.extensions: list[str] = raw_config.get('extensions', []) @property def values(self) -> dict[str, _Opt]: return self._options @property def overrides(self) -> dict[str, Any]: return self._overrides @classmethod def read( cls: type[Config], confdir: str | os.PathLike[str], overrides: dict[str, Any] | None = None, tags: Tags | None = None, ) -> Config: """Create a Config object from configuration file.""" filename = Path(confdir, CONFIG_FILENAME) if not filename.is_file(): raise ConfigError( __("config directory doesn't contain a conf.py file (%s)") % confdir ) namespace = eval_config_file(filename, tags) # Note: Old sphinx projects have been configured as "language = None" because # sphinx-quickstart previously generated this by default. # To keep compatibility, they should be fallback to 'en' for a while # (This conversion should not be removed before 2025-01-01). if namespace.get('language', ...) is None: logger.warning( __( "Invalid configuration value found: 'language = None'. " 'Update your configuration to a valid language code. ' "Falling back to 'en' (English)." ) ) namespace['language'] = 'en' return cls(namespace, overrides) def convert_overrides(self, name: str, value: str) -> Any: opt = self._options[name] default = opt.default valid_types = opt.valid_types if valid_types == Any: return value if isinstance(valid_types, ENUM): if False in valid_types._candidates and value == '0': return False if True in valid_types._candidates and value == '1': return True return value elif type(default) is bool or (bool in valid_types): if value == '0': return False if value == '1': return True if len(valid_types) > 1: return value msg = __("'%s' must be '0' or '1', got '%s'") % (name, value) raise ConfigError(msg) if isinstance(default, dict): raise ValueError( # NoQA: TRY004 __( 'cannot override dictionary config setting %r, ' 'ignoring (use %r to set individual elements)' ) % (name, f'{name}.key=value') ) if isinstance(default, list): return value.split(',') if isinstance(default, int): try: return int(value) except ValueError as exc: raise ValueError( __('invalid number %r for config value %r, ignoring') % (value, name) ) from exc if callable(default): return value if isinstance(default, str) or default is None: return value raise ValueError( __('cannot override config setting %r with unsupported type, ignoring') % name ) @staticmethod def pre_init_values() -> None: # method only retained for compatibility pass # warnings.warn( # 'Config.pre_init_values() will be removed in Sphinx 9.0 or later', # RemovedInSphinx90Warning, stacklevel=2) def init_values(self) -> None: # method only retained for compatibility self._report_override_warnings() # warnings.warn( # 'Config.init_values() will be removed in Sphinx 9.0 or later', # RemovedInSphinx90Warning, stacklevel=2) def _report_override_warnings(self) -> None: for name in self._overrides: if name not in self._options: logger.warning( __('unknown config value %r in override, ignoring'), name ) def __repr__(self) -> str: values = [] for opt_name in self._options: try: opt_value = getattr(self, opt_name) except Exception: opt_value = '' values.append(f'{opt_name}={opt_value!r}') return self.__class__.__qualname__ + '(' + ', '.join(values) + ')' def __setattr__(self, key: str, value: object) -> None: # Ensure aliases update their counterpart. if key == 'master_doc': super().__setattr__('root_doc', value) elif key == 'root_doc': super().__setattr__('master_doc', value) elif key == 'copyright': super().__setattr__('project_copyright', value) elif key == 'project_copyright': super().__setattr__('copyright', value) super().__setattr__(key, value) def __getattr__(self, name: str) -> Any: if name in self._options: # first check command-line overrides if name in self._overrides: value = self._overrides[name] if not isinstance(value, str): self.__dict__[name] = value return value try: value = self.convert_overrides(name, value) except ValueError as exc: logger.warning('%s', exc) else: self.__setattr__(name, value) return value # then check values from 'conf.py' if name in self._raw_config: value = self._raw_config[name] self.__setattr__(name, value) return value # finally, fall back to the default value default = self._options[name].default if callable(default): return default(self) self.__dict__[name] = default return default if name.startswith('_'): msg = f'{self.__class__.__name__!r} object has no attribute {name!r}' raise AttributeError(msg) msg = __('No such config value: %r') % name raise AttributeError(msg) def __getitem__(self, name: str) -> Any: return getattr(self, name) def __setitem__(self, name: str, value: Any) -> None: setattr(self, name, value) def __delitem__(self, name: str) -> None: delattr(self, name) def __contains__(self, name: str) -> bool: return name in self._options def __iter__(self) -> Iterator[ConfigValue]: for name, opt in self._options.items(): yield ConfigValue(name, getattr(self, name), opt.rebuild) def add( self, name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM, description: str = '', ) -> None: if name in self._options: raise ExtensionError(__('Config value %r already present') % name) # standardise rebuild if isinstance(rebuild, bool): rebuild = 'env' if rebuild else '' # standardise valid_types valid_types = _validate_valid_types(types) self._options[name] = _Opt(default, rebuild, valid_types, description) def filter(self, rebuild: Set[_ConfigRebuild]) -> Iterator[ConfigValue]: if isinstance(rebuild, str): return (value for value in self if value.rebuild == rebuild) return (value for value in self if value.rebuild in rebuild) def __getstate__(self) -> dict[str, Any]: """Obtains serializable data for pickling.""" # remove potentially pickling-problematic values from config __dict__ = { key: value for key, value in self.__dict__.items() if not key.startswith('_') and is_serializable(value) } # create a pickleable copy of ``self._options`` __dict__['_options'] = _options = {} for name, opt in self._options.items(): if not isinstance(opt, _Opt) and isinstance(opt, tuple) and len(opt) <= 3: # Fix for Furo's ``_update_default``. self._options[name] = opt = _Opt(*opt) real_value = getattr(self, name) if not is_serializable(real_value): if opt.rebuild: # if the value is not cached, then any build that utilises this cache # will always mark the config value as changed, # and thus always invalidate the cache and perform a rebuild. logger.warning( __( 'cannot cache unpickleable configuration value: %r ' '(because it contains a function, class, or module object)' ), name, type='config', subtype='cache', once=True, ) # omit unserializable value real_value = None # valid_types is also omitted _options[name] = real_value, opt.rebuild return __dict__ def __setstate__(self, state: dict[str, Any]) -> None: self._overrides = {} self._options = { name: _Opt(real_value, rebuild, frozenset()) for name, (real_value, rebuild) in state.pop('_options').items() } self._raw_config = {} self.__dict__.update(state) def eval_config_file( filename: str | os.PathLike[str], tags: Tags | None ) -> dict[str, Any]: """Evaluate a config file.""" filename = Path(filename) namespace: dict[str, Any] = { '__file__': str(filename), 'tags': tags, } with chdir(filename.parent): # during executing config file, current dir is changed to ``confdir``. try: code = compile(filename.read_bytes(), filename, 'exec') exec(code, namespace) # NoQA: S102 except SyntaxError as err: msg = __('There is a syntax error in your configuration file: %s\n') raise ConfigError(msg % err) from err except SystemExit as exc: msg = __( 'The configuration file (or one of the modules it imports) ' 'called sys.exit()' ) raise ConfigError(msg) from exc except ConfigError: # pass through ConfigError from conf.py as is. It will be shown in console. raise except Exception as exc: msg = __('There is a programmable error in your configuration file:\n\n%s') raise ConfigError(msg % traceback.format_exc()) from exc return namespace def _validate_valid_types( valid_types: type | Collection[type] | ENUM, / ) -> frozenset[type] | ENUM: if not valid_types: return frozenset() if isinstance(valid_types, frozenset | ENUM): return valid_types if isinstance(valid_types, type): return frozenset((valid_types,)) if valid_types is Any: return frozenset({Any}) # type: ignore[arg-type] if isinstance(valid_types, set): return frozenset(valid_types) try: return frozenset(valid_types) except TypeError: logger.warning(__('Failed to convert %r to a frozenset'), valid_types) return frozenset() def convert_source_suffix(app: Sphinx, config: Config) -> None: """Convert old styled source_suffix to new styled one. * old style: str or list * new style: a dict which maps from fileext to filetype """ source_suffix = config.source_suffix if isinstance(source_suffix, str): # if str, considers as default filetype (None) # # The default filetype is determined on later step. # By default, it is considered as restructuredtext. config.source_suffix = {source_suffix: 'restructuredtext'} logger.info( __('Converting `source_suffix = %r` to `source_suffix = %r`.'), source_suffix, config.source_suffix, ) elif isinstance(source_suffix, list | tuple): # if list, considers as all of them are default filetype config.source_suffix = dict.fromkeys(source_suffix, 'restructuredtext') logger.info( __('Converting `source_suffix = %r` to `source_suffix = %r`.'), source_suffix, config.source_suffix, ) elif not isinstance(source_suffix, dict): msg = __( "The config value `source_suffix' expects a dictionary, " "a string, or a list of strings. Got `%r' instead (type %s)." ) raise ConfigError(msg % (source_suffix, type(source_suffix))) def convert_highlight_options(app: Sphinx, config: Config) -> None: """Convert old styled highlight_options to new styled one. * old style: options * new style: a dict which maps from language name to options """ options = config.highlight_options if options and not all(isinstance(v, dict) for v in options.values()): # old styled option detected because all values are not dictionary. config.highlight_options = {config.highlight_language: options} def init_numfig_format(app: Sphinx, config: Config) -> None: """Initialize :confval:`numfig_format`.""" numfig_format = { 'section': _('Section %s'), 'figure': _('Fig. %s'), 'table': _('Table %s'), 'code-block': _('Listing %s'), } # override default labels by configuration numfig_format.update(config.numfig_format) config.numfig_format = numfig_format def evaluate_copyright_placeholders(_app: Sphinx, config: Config) -> None: """Replace copyright year placeholders (%Y) with the current year.""" replace_yr = str(time.localtime().tm_year) for k in ('copyright', 'epub_copyright'): if k in config: value: str | Sequence[str] = config[k] if isinstance(value, str): if '%Y' in value: config[k] = value.replace('%Y', replace_yr) else: if any('%Y' in line for line in value): items = (line.replace('%Y', replace_yr) for line in value) config[k] = type(value)(items) # type: ignore[call-arg] def correct_copyright_year(_app: Sphinx, config: Config) -> None: """Correct values of copyright year that are not coherent with the SOURCE_DATE_EPOCH environment variable (if set) See https://reproducible-builds.org/specs/source-date-epoch/ """ if source_date_epoch := int(getenv('SOURCE_DATE_EPOCH', '0')): source_date_epoch_year = time.gmtime(source_date_epoch).tm_year else: return # If the current year is the replacement year, there's no work to do. # We also skip replacement years that are in the future. current_year = time.localtime().tm_year if current_year <= source_date_epoch_year: return current_yr = str(current_year) replace_yr = str(source_date_epoch_year) for k in ('copyright', 'epub_copyright'): if k in config: value: str | Sequence[str] = config[k] if isinstance(value, str): config[k] = _substitute_copyright_year(value, current_yr, replace_yr) else: items = ( _substitute_copyright_year(x, current_yr, replace_yr) for x in value ) config[k] = type(value)(items) # type: ignore[call-arg] def _substitute_copyright_year( copyright_line: str, current_year: str, replace_year: str ) -> str: """Replace the year in a single copyright line. Legal formats are: * ``YYYY`` * ``YYYY,`` * ``YYYY `` * ``YYYY-YYYY`` * ``YYYY-YYYY,`` * ``YYYY-YYYY `` The final year in the string is replaced with ``replace_year``. """ if len(copyright_line) < 4 or not copyright_line[:4].isdigit(): return copyright_line if copyright_line[:4] == current_year and copyright_line[4:5] in {'', ' ', ','}: return replace_year + copyright_line[4:] if copyright_line[4:5] != '-': return copyright_line if ( copyright_line[5:9].isdigit() and copyright_line[5:9] == current_year and copyright_line[9:10] in {'', ' ', ','} ): return copyright_line[:5] + replace_year + copyright_line[9:] return copyright_line def check_confval_types(app: Sphinx | None, config: Config) -> None: """Check all values for deviation from the default value's type, since that can result in TypeErrors all over the place NB. """ for name, opt in config._options.items(): default = opt.default valid_types = opt.valid_types value = getattr(config, name) if callable(default): default = default(config) # evaluate default value if default is None and not valid_types: continue # neither inferable nor explicitly annotated types if valid_types == frozenset({Any}): # any type of value is accepted continue if isinstance(valid_types, ENUM): if not valid_types.match(value): msg = __( 'The config value `{name}` has to be a one of {candidates}, ' 'but `{current}` is given.' ) logger.warning( msg.format( name=name, current=value, candidates=valid_types._candidates ), once=True, ) continue type_value = type(value) type_default = type(default) if type_value is type_default: # attempt to infer the type continue if type_value in valid_types: # check explicitly listed types if frozenset in valid_types and type_value in {list, tuple, set}: setattr(config, name, frozenset(value)) elif tuple in valid_types and type_value is list: setattr(config, name, tuple(value)) continue common_bases = {*type_value.__bases__, type_value} & set(type_default.__bases__) common_bases.discard(object) if common_bases: continue # at least we share a non-trivial base class if valid_types: msg = __( "The config value `{name}' has type `{current.__name__}'; " 'expected {permitted}.' ) wrapped_valid_types = sorted(f"`{c.__name__}'" for c in valid_types) if len(wrapped_valid_types) > 2: permitted = ( ', '.join(wrapped_valid_types[:-1]) + f', or {wrapped_valid_types[-1]}' ) else: permitted = ' or '.join(wrapped_valid_types) logger.warning( msg.format(name=name, current=type_value, permitted=permitted), once=True, ) else: msg = __( "The config value `{name}' has type `{current.__name__}', " "defaults to `{default.__name__}'." ) logger.warning( msg.format(name=name, current=type_value, default=type_default), once=True, ) def check_primary_domain(app: Sphinx, config: Config) -> None: primary_domain = config.primary_domain if primary_domain and not app.registry.has_domain(primary_domain): logger.warning(__('primary_domain %r not found, ignored.'), primary_domain) config.primary_domain = None def check_master_doc( app: Sphinx, env: BuildEnvironment, added: Set[str], changed: Set[str], removed: Set[str], ) -> Iterable[str]: """Sphinx 2.0 changed the default from 'contents' to 'index'.""" docnames = app.project.docnames if ( app.config.master_doc == 'index' and 'index' not in docnames and 'contents' in docnames ): logger.warning( __( 'Sphinx now uses "index" as the master document by default. ' 'To keep pre-2.0 behaviour, set "master_doc = \'contents\'".' ) ) app.config.master_doc = 'contents' return changed def setup(app: Sphinx) -> ExtensionMetadata: app.connect('config-inited', convert_source_suffix, priority=800) app.connect('config-inited', convert_highlight_options, priority=800) app.connect('config-inited', init_numfig_format, priority=800) app.connect('config-inited', evaluate_copyright_placeholders, priority=795) app.connect('config-inited', correct_copyright_year, priority=800) app.connect('config-inited', check_confval_types, priority=800) app.connect('config-inited', check_primary_domain, priority=800) app.connect('env-get-outdated', check_master_doc) return { 'version': 'builtin', 'parallel_read_safe': True, 'parallel_write_safe': True, }