diff options
Diffstat (limited to 'sphinx/config.py')
| -rw-r--r-- | sphinx/config.py | 105 |
1 files changed, 61 insertions, 44 deletions
diff --git a/sphinx/config.py b/sphinx/config.py index 090875a79..73f442cf9 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -5,7 +5,7 @@ Build configuration file handling. - :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS. + :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ @@ -13,12 +13,12 @@ import re from os import path, environ import shlex -from six import PY3, iteritems, string_types, binary_type, integer_types +from six import PY2, PY3, iteritems, string_types, binary_type, text_type, integer_types from sphinx.errors import ConfigError from sphinx.locale import l_ from sphinx.util.osutil import make_filename, cd -from sphinx.util.pycompat import execfile_ +from sphinx.util.pycompat import execfile_, NoneType nonascii_re = re.compile(br'[\x80-\xff]') @@ -27,10 +27,13 @@ if PY3: CONFIG_SYNTAX_ERROR += "\nDid you change the syntax from 2.x to 3.x?" CONFIG_EXIT_ERROR = "The configuration file (or one of the modules it imports) " \ "called sys.exit()" +CONFIG_TYPE_WARNING = "The config value `{name}' has type `{current.__name__}', " \ + "defaults to `{default.__name__}.'" -IGNORE_CONFIG_TYPE_CHECKS = ( - 'html_domain_indices', 'latex_domain_indices', 'texinfo_domain_indices' -) + +string_classes = [text_type] +if PY2: + string_classes.append(binary_type) # => [str, unicode] class Config(object): @@ -50,33 +53,36 @@ class Config(object): version = ('', 'env'), release = ('', 'env'), today = ('', 'env'), - today_fmt = (None, 'env'), # the real default is locale-dependent + # the real default is locale-dependent + today_fmt = (None, 'env', string_classes), - language = (None, 'env'), + language = (None, 'env', string_classes), locale_dirs = ([], 'env'), + figure_language_filename = ('{root}.{language}{ext}', 'env', [str]), master_doc = ('contents', 'env'), source_suffix = (['.rst'], 'env'), source_encoding = ('utf-8-sig', 'env'), source_parsers = ({}, 'env'), exclude_patterns = ([], 'env'), - default_role = (None, 'env'), + default_role = (None, 'env', string_classes), add_function_parentheses = (True, 'env'), add_module_names = (True, 'env'), trim_footnote_reference_space = (False, 'env'), show_authors = (False, 'env'), - pygments_style = (None, 'html'), - highlight_language = ('python', 'env'), + pygments_style = (None, 'html', string_classes), + highlight_language = ('default', 'env'), highlight_options = ({}, 'env'), templates_path = ([], 'html'), - template_bridge = (None, 'html'), + template_bridge = (None, 'html', string_classes), keep_warnings = (False, 'env'), + suppress_warnings = ([], 'env'), modindex_common_prefix = ([], 'html'), - rst_epilog = (None, 'env'), - rst_prolog = (None, 'env'), + rst_epilog = (None, 'env', string_classes), + rst_prolog = (None, 'env', string_classes), trim_doctest_flags = (True, 'env'), - primary_domain = ('py', 'env'), - needs_sphinx = (None, None), + primary_domain = ('py', 'env', [NoneType]), + needs_sphinx = (None, None, string_classes), needs_extensions = ({}, None), nitpicky = (False, 'env'), nitpick_ignore = ([], 'html'), @@ -93,36 +99,36 @@ class Config(object): html_theme_options = ({}, 'html'), html_title = (lambda self: l_('%s %s documentation') % (self.project, self.release), - 'html'), + 'html', string_classes), html_short_title = (lambda self: self.html_title, 'html'), - html_style = (None, 'html'), - html_logo = (None, 'html'), - html_favicon = (None, 'html'), + html_style = (None, 'html', string_classes), + html_logo = (None, 'html', string_classes), + html_favicon = (None, 'html', string_classes), html_static_path = ([], 'html'), html_extra_path = ([], 'html'), # the real default is locale-dependent - html_last_updated_fmt = (None, 'html'), + html_last_updated_fmt = (None, 'html', string_classes), html_use_smartypants = (True, 'html'), - html_translator_class = (None, 'html'), + html_translator_class = (None, 'html', string_classes), html_sidebars = ({}, 'html'), html_additional_pages = ({}, 'html'), html_use_modindex = (True, 'html'), # deprecated - html_domain_indices = (True, 'html'), + html_domain_indices = (True, 'html', [list]), html_add_permalinks = (u'\u00B6', 'html'), html_use_index = (True, 'html'), html_split_index = (False, 'html'), html_copy_source = (True, 'html'), html_show_sourcelink = (True, 'html'), html_use_opensearch = ('', 'html'), - html_file_suffix = (None, 'html'), - html_link_suffix = (None, 'html'), + html_file_suffix = (None, 'html', string_classes), + html_link_suffix = (None, 'html', string_classes), html_show_copyright = (True, 'html'), html_show_sphinx = (True, 'html'), html_context = ({}, 'html'), html_output_encoding = ('utf-8', 'html'), html_compact_lists = (True, 'html'), html_secnumber_suffix = ('. ', 'html'), - html_search_language = (None, 'html'), + html_search_language = (None, 'html', string_classes), html_search_options = ({}, 'html'), html_search_scorer = ('', None), html_scaled_image_link = (True, 'html'), @@ -139,17 +145,17 @@ class Config(object): # Apple help options applehelp_bundle_name = (lambda self: make_filename(self.project), 'applehelp'), - applehelp_bundle_id = (None, 'applehelp'), + applehelp_bundle_id = (None, 'applehelp', string_classes), applehelp_dev_region = ('en-us', 'applehelp'), applehelp_bundle_version = ('1', 'applehelp'), - applehelp_icon = (None, 'applehelp'), + applehelp_icon = (None, 'applehelp', string_classes), applehelp_kb_product = (lambda self: '%s-%s' % (make_filename(self.project), self.release), 'applehelp'), - applehelp_kb_url = (None, 'applehelp'), - applehelp_remote_url = (None, 'applehelp'), - applehelp_index_anchors = (False, 'applehelp'), - applehelp_min_term_length = (None, 'applehelp'), + applehelp_kb_url = (None, 'applehelp', string_classes), + applehelp_remote_url = (None, 'applehelp', string_classes), + applehelp_index_anchors = (False, 'applehelp', string_classes), + applehelp_min_term_length = (None, 'applehelp', string_classes), applehelp_stopwords = (lambda self: self.language or 'en', 'applehelp'), applehelp_locale = (lambda self: self.language or 'en', 'applehelp'), applehelp_title = (lambda self: self.project + ' Help', 'applehelp'), @@ -170,7 +176,9 @@ class Config(object): epub_theme = ('epub', 'html'), epub_theme_options = ({}, 'html'), epub_title = (lambda self: self.html_title, 'html'), + epub3_description = ('', 'epub3', string_classes), epub_author = ('unknown', 'html'), + epub3_contributor = ('unknown', 'epub3', string_classes), epub_language = (lambda self: self.language or 'en', 'html'), epub_publisher = ('unknown', 'html'), epub_copyright = (lambda self: self.copyright, 'html'), @@ -189,6 +197,7 @@ class Config(object): epub_max_image_width = (0, 'env'), epub_show_urls = ('inline', 'html'), epub_use_index = (lambda self: self.html_use_index, 'html'), + epub3_page_progression_direction = ('ltr', 'epub3', string_classes), # LaTeX options latex_documents = (lambda self: [(self.master_doc, @@ -196,11 +205,13 @@ class Config(object): self.project, '', 'manual')], None), - latex_logo = (None, None), + latex_logo = (None, None, string_classes), latex_appendices = ([], None), + # now deprecated - use latex_toplevel_sectioning latex_use_parts = (False, None), + latex_toplevel_sectioning = (None, None, [str]), latex_use_modindex = (True, None), # deprecated - latex_domain_indices = (True, None), + latex_domain_indices = (True, None, [list]), latex_show_urls = ('no', None), latex_show_pagerefs = (False, None), # paper_size and font_size are still separate values @@ -236,13 +247,14 @@ class Config(object): None), texinfo_appendices = ([], None), texinfo_elements = ({}, None), - texinfo_domain_indices = (True, None), + texinfo_domain_indices = (True, None, [list]), texinfo_show_urls = ('footnote', None), texinfo_no_detailmenu = (False, None), # linkcheck options linkcheck_ignore = ([], None), - linkcheck_timeout = (None, None), + linkcheck_retries = (1, None), + linkcheck_timeout = (None, None, [int]), linkcheck_workers = (5, None), linkcheck_anchors = (True, None), @@ -292,25 +304,30 @@ class Config(object): # NB. since config values might use l_() we have to wait with calling # this method until i18n is initialized for name in self._raw_config: - if name in IGNORE_CONFIG_TYPE_CHECKS: - continue # for a while, ignore multiple types config value. see #1781 - if name not in Config.config_values: + if name not in self.values: continue # we don't know a default value - default, dummy_rebuild = Config.config_values[name] + settings = self.values[name] + default, dummy_rebuild = settings[:2] + permitted = settings[2] if len(settings) == 3 else () + if hasattr(default, '__call__'): default = default(self) # could invoke l_() - if default is None: - continue + if default is None and not permitted: + continue # neither inferrable nor expliclitly permitted types current = self[name] if type(current) is type(default): continue + if type(current) in permitted: + continue + common_bases = (set(type(current).__bases__ + (type(current),)) & set(type(default).__bases__)) common_bases.discard(object) if common_bases: continue # at least we share a non-trivial base class - warn("the config value %r has type `%s', defaults to `%s.'" % - (name, type(current).__name__, type(default).__name__)) + + warn(CONFIG_TYPE_WARNING.format( + name=name, current=type(current), default=type(default))) def check_unicode(self, warn): # check all string values for non-ASCII characters in bytestrings, |