/create_batch_for_workflow/pymodules/python2.7/lib/python/Sphinx-1.2.3-py2.7.egg/sphinx/config.py
Python | 284 lines | 259 code | 8 blank | 17 comment | 1 complexity | 4eebab159a44b83e34cc8f75de0b2b1c MD5 | raw file
1# -*- coding: utf-8 -*-
2"""
3 sphinx.config
4 ~~~~~~~~~~~~~
5
6 Build configuration file handling.
7
8 :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
9 :license: BSD, see LICENSE for details.
10"""
11
12import os
13import re
14import sys
15from os import path
16
17from sphinx.errors import ConfigError
18from sphinx.locale import l_
19from sphinx.util.osutil import make_filename
20from sphinx.util.pycompat import bytes, b, execfile_
21
22nonascii_re = re.compile(b(r'[\x80-\xff]'))
23
24CONFIG_SYNTAX_ERROR = "There is a syntax error in your configuration file: %s"
25if sys.version_info >= (3, 0):
26 CONFIG_SYNTAX_ERROR += "\nDid you change the syntax from 2.x to 3.x?"
27
28class Config(object):
29 """
30 Configuration file abstraction.
31 """
32
33 # the values are: (default, what needs to be rebuilt if changed)
34
35 # If you add a value here, don't forget to include it in the
36 # quickstart.py file template as well as in the docs!
37
38 config_values = dict(
39 # general options
40 project = ('Python', 'env'),
41 copyright = ('', 'html'),
42 version = ('', 'env'),
43 release = ('', 'env'),
44 today = ('', 'env'),
45 today_fmt = (None, 'env'), # the real default is locale-dependent
46
47 language = (None, 'env'),
48 locale_dirs = ([], 'env'),
49
50 master_doc = ('contents', 'env'),
51 source_suffix = ('.rst', 'env'),
52 source_encoding = ('utf-8-sig', 'env'),
53 exclude_patterns = ([], 'env'),
54 # the next three are all deprecated now
55 unused_docs = ([], 'env'),
56 exclude_trees = ([], 'env'),
57 exclude_dirnames = ([], 'env'),
58 default_role = (None, 'env'),
59 add_function_parentheses = (True, 'env'),
60 add_module_names = (True, 'env'),
61 trim_footnote_reference_space = (False, 'env'),
62 show_authors = (False, 'env'),
63 pygments_style = (None, 'html'),
64 highlight_language = ('python', 'env'),
65 templates_path = ([], 'html'),
66 template_bridge = (None, 'html'),
67 keep_warnings = (False, 'env'),
68 modindex_common_prefix = ([], 'html'),
69 rst_epilog = (None, 'env'),
70 rst_prolog = (None, 'env'),
71 trim_doctest_flags = (True, 'env'),
72 primary_domain = ('py', 'env'),
73 needs_sphinx = (None, None),
74 nitpicky = (False, 'env'),
75 nitpick_ignore = ([], 'html'),
76
77 # HTML options
78 html_theme = ('default', 'html'),
79 html_theme_path = ([], 'html'),
80 html_theme_options = ({}, 'html'),
81 html_title = (lambda self: l_('%s %s documentation') %
82 (self.project, self.release),
83 'html'),
84 html_short_title = (lambda self: self.html_title, 'html'),
85 html_style = (None, 'html'),
86 html_logo = (None, 'html'),
87 html_favicon = (None, 'html'),
88 html_static_path = ([], 'html'),
89 html_extra_path = ([], 'html'),
90 # the real default is locale-dependent
91 html_last_updated_fmt = (None, 'html'),
92 html_use_smartypants = (True, 'html'),
93 html_translator_class = (None, 'html'),
94 html_sidebars = ({}, 'html'),
95 html_additional_pages = ({}, 'html'),
96 html_use_modindex = (True, 'html'), # deprecated
97 html_domain_indices = (True, 'html'),
98 html_add_permalinks = (u'\u00B6', 'html'),
99 html_use_index = (True, 'html'),
100 html_split_index = (False, 'html'),
101 html_copy_source = (True, 'html'),
102 html_show_sourcelink = (True, 'html'),
103 html_use_opensearch = ('', 'html'),
104 html_file_suffix = (None, 'html'),
105 html_link_suffix = (None, 'html'),
106 html_show_copyright = (True, 'html'),
107 html_show_sphinx = (True, 'html'),
108 html_context = ({}, 'html'),
109 html_output_encoding = ('utf-8', 'html'),
110 html_compact_lists = (True, 'html'),
111 html_secnumber_suffix = ('. ', 'html'),
112 html_search_language = (None, 'html'),
113 html_search_options = ({}, 'html'),
114 html_search_scorer = ('', None),
115
116 # HTML help only options
117 htmlhelp_basename = (lambda self: make_filename(self.project), None),
118
119 # Qt help only options
120 qthelp_basename = (lambda self: make_filename(self.project), None),
121
122 # Devhelp only options
123 devhelp_basename = (lambda self: make_filename(self.project), None),
124
125 # Epub options
126 epub_basename = (lambda self: make_filename(self.project), None),
127 epub_theme = ('epub', 'html'),
128 epub_theme_options = ({}, 'html'),
129 epub_title = (lambda self: self.html_title, 'html'),
130 epub_author = ('unknown', 'html'),
131 epub_language = (lambda self: self.language or 'en', 'html'),
132 epub_publisher = ('unknown', 'html'),
133 epub_copyright = (lambda self: self.copyright, 'html'),
134 epub_identifier = ('unknown', 'html'),
135 epub_scheme = ('unknown', 'html'),
136 epub_uid = ('unknown', 'env'),
137 epub_cover = ((), 'env'),
138 epub_guide = ((), 'env'),
139 epub_pre_files = ([], 'env'),
140 epub_post_files = ([], 'env'),
141 epub_exclude_files = ([], 'env'),
142 epub_tocdepth = (3, 'env'),
143 epub_tocdup = (True, 'env'),
144 epub_tocscope = ('default', 'env'),
145 epub_fix_images = (False, 'env'),
146 epub_max_image_width = (0, 'env'),
147 epub_show_urls = ('inline', 'html'),
148 epub_use_index = (lambda self: self.html_use_index, 'html'),
149
150 # LaTeX options
151 latex_documents = (lambda self: [(self.master_doc,
152 make_filename(self.project) + '.tex',
153 self.project,
154 '', 'manual')],
155 None),
156 latex_logo = (None, None),
157 latex_appendices = ([], None),
158 latex_use_parts = (False, None),
159 latex_use_modindex = (True, None), # deprecated
160 latex_domain_indices = (True, None),
161 latex_show_urls = ('no', None),
162 latex_show_pagerefs = (False, None),
163 # paper_size and font_size are still separate values
164 # so that you can give them easily on the command line
165 latex_paper_size = ('letter', None),
166 latex_font_size = ('10pt', None),
167 latex_elements = ({}, None),
168 latex_additional_files = ([], None),
169 latex_docclass = ({}, None),
170 # now deprecated - use latex_elements
171 latex_preamble = ('', None),
172
173 # text options
174 text_sectionchars = ('*=-~"+`', 'env'),
175 text_newlines = ('unix', 'env'),
176
177 # manpage options
178 man_pages = (lambda self: [(self.master_doc,
179 make_filename(self.project).lower(),
180 '%s %s' % (self.project, self.release),
181 [], 1)],
182 None),
183 man_show_urls = (False, None),
184
185 # Texinfo options
186 texinfo_documents = (lambda self: [(self.master_doc,
187 make_filename(self.project).lower(),
188 self.project, '',
189 make_filename(self.project),
190 'The %s reference manual.' %
191 make_filename(self.project),
192 'Python')],
193 None),
194 texinfo_appendices = ([], None),
195 texinfo_elements = ({}, None),
196 texinfo_domain_indices = (True, None),
197 texinfo_show_urls = ('footnote', None),
198 texinfo_no_detailmenu = (False, None),
199
200 # linkcheck options
201 linkcheck_ignore = ([], None),
202 linkcheck_timeout = (None, None),
203 linkcheck_workers = (5, None),
204 linkcheck_anchors = (True, None),
205
206 # gettext options
207 gettext_compact = (True, 'gettext'),
208
209 # XML options
210 xml_pretty = (True, 'env'),
211 )
212
213 def __init__(self, dirname, filename, overrides, tags):
214 self.overrides = overrides
215 self.values = Config.config_values.copy()
216 config = {}
217 if "extensions" in overrides:
218 config["extensions"] = overrides["extensions"]
219 if dirname is not None:
220 config_file = path.join(dirname, filename)
221 config['__file__'] = config_file
222 config['tags'] = tags
223 olddir = os.getcwd()
224 try:
225 # we promise to have the config dir as current dir while the
226 # config file is executed
227 os.chdir(dirname)
228 try:
229 execfile_(filename, config)
230 except SyntaxError, err:
231 raise ConfigError(CONFIG_SYNTAX_ERROR % err)
232 finally:
233 os.chdir(olddir)
234
235 self._raw_config = config
236 # these two must be preinitialized because extensions can add their
237 # own config values
238 self.setup = config.get('setup', None)
239 self.extensions = config.get('extensions', [])
240
241 def check_unicode(self, warn):
242 # check all string values for non-ASCII characters in bytestrings,
243 # since that can result in UnicodeErrors all over the place
244 for name, value in self._raw_config.iteritems():
245 if isinstance(value, bytes) and nonascii_re.search(value):
246 warn('the config value %r is set to a string with non-ASCII '
247 'characters; this can lead to Unicode errors occurring. '
248 'Please use Unicode strings, e.g. %r.' % (name, u'Content')
249 )
250
251 def init_values(self):
252 config = self._raw_config
253 for valname, value in self.overrides.iteritems():
254 if '.' in valname:
255 realvalname, key = valname.split('.', 1)
256 config.setdefault(realvalname, {})[key] = value
257 else:
258 config[valname] = value
259 for name in config:
260 if name in self.values:
261 self.__dict__[name] = config[name]
262 del self._raw_config
263
264 def __getattr__(self, name):
265 if name.startswith('_'):
266 raise AttributeError(name)
267 if name not in self.values:
268 raise AttributeError('No such config value: %s' % name)
269 default = self.values[name][0]
270 if hasattr(default, '__call__'):
271 return default(self)
272 return default
273
274 def __getitem__(self, name):
275 return getattr(self, name)
276
277 def __setitem__(self, name, value):
278 setattr(self, name, value)
279
280 def __delitem__(self, name):
281 delattr(self, name)
282
283 def __contains__(self, name):
284 return name in self.values