def setup(app):
app.setup_extension('sphinx.builders.html')
app.add_builder(AppleHelpBuilder)
app.add_config_value('applehelp_bundle_name',
lambda self: make_filename(self.project), 'applehelp')
app.add_config_value('applehelp_bundle_id', None, 'applehelp', string_classes)
app.add_config_value('applehelp_dev_region', 'en-us', 'applehelp')
app.add_config_value('applehelp_bundle_version', '1', 'applehelp')
app.add_config_value('applehelp_icon', None, 'applehelp', string_classes)
app.add_config_value('applehelp_kb_product',
lambda self: '%s-%s' % (make_filename(self.project), self.release),
'applehelp')
app.add_config_value('applehelp_kb_url', None, 'applehelp', string_classes)
app.add_config_value('applehelp_remote_url', None, 'applehelp', string_classes)
app.add_config_value('applehelp_index_anchors', False, 'applehelp', string_classes)
app.add_config_value('applehelp_min_term_length', None, 'applehelp', string_classes)
app.add_config_value('applehelp_stopwords',
lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_locale', lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_title', lambda self: self.project + ' Help', 'applehelp')
app.add_config_value('applehelp_codesign_identity',
lambda self: environ.get('CODE_SIGN_IDENTITY', None),
'applehelp'),
app.add_config_value('applehelp_codesign_flags',
lambda self: shlex.split(environ.get('OTHER_CODE_SIGN_FLAGS', '')),
'applehelp'),
app.add_config_value('applehelp_indexer_path', '/usr/bin/hiutil', 'applehelp')
app.add_config_value('applehelp_codesign_path', '/usr/bin/codesign', 'applehelp')
app.add_config_value('applehelp_disable_external_tools', False, None)
def setup(app):
app.add_builder(TexinfoBuilder)
app.add_config_value('texinfo_documents',
lambda self: [(self.master_doc, make_filename(self.project).lower(),
self.project, '', make_filename(self.project),
'The %s reference manual.' %
make_filename(self.project),
'Python')],
None)
app.add_config_value('texinfo_appendices', [], None)
app.add_config_value('texinfo_elements', {}, None)
app.add_config_value('texinfo_domain_indices', True, None, [list])
app.add_config_value('texinfo_show_urls', 'footnote', None)
app.add_config_value('texinfo_no_detailmenu', False, None)
def setup(app):
app.add_builder(LaTeXBuilder)
app.connect('builder-inited', validate_config_values)
app.add_config_value('latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')],
None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_keep_old_macro_names', True, None)
# now deprecated - use latex_toplevel_sectioning
app.add_config_value('latex_use_parts', False, None)
app.add_config_value('latex_toplevel_sectioning', None, None, [str])
app.add_config_value('latex_use_modindex', True, None) # deprecated
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
# paper_size and font_size are still separate values
# so that you can give them easily on the command line
app.add_config_value('latex_paper_size', 'letter', None)
app.add_config_value('latex_font_size', '10pt', None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
app.add_config_value('latex_docclass', {}, None)
# now deprecated - use latex_elements
app.add_config_value('latex_preamble', '', None)
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(LaTeXBuilder)
app.connect('builder-inited', validate_config_values)
app.add_config_value('latex_engine', default_latex_engine, None,
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))
app.add_config_value('latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')],
None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_keep_old_macro_names', False, None)
app.add_config_value('latex_use_latex_multicolumn', False, None)
app.add_config_value('latex_toplevel_sectioning', None, None, [str])
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
app.add_config_value('latex_docclass', default_latex_docclass, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(EpubBuilder)
# config values
app.add_config_value('epub_basename', lambda self: make_filename(self.project), None)
app.add_config_value('epub_theme', 'epub', 'html')
app.add_config_value('epub_theme_options', {}, 'html')
app.add_config_value('epub_title', lambda self: self.html_title, 'html')
app.add_config_value('epub_author', 'unknown', 'html')
app.add_config_value('epub_language', lambda self: self.language or 'en', 'html')
app.add_config_value('epub_publisher', 'unknown', 'html')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'html')
app.add_config_value('epub_identifier', 'unknown', 'html')
app.add_config_value('epub_scheme', 'unknown', 'html')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'html')
app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'html')
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.setup_extension('sphinx.builders.html')
app.add_builder(QtHelpBuilder)
app.add_config_value('qthelp_basename', lambda self: make_filename(self.project), None)
app.add_config_value('qthelp_theme', 'nonav', 'html')
app.add_config_value('qthelp_theme_options', {}, 'html')
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(LaTeXBuilder)
app.connect('config-inited', validate_config_values)
app.add_config_value('latex_engine', default_latex_engine, None,
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))
app.add_config_value(
'latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')], None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_use_latex_multicolumn', False, None)
app.add_config_value('latex_toplevel_sectioning', None, None,
ENUM('part', 'chapter', 'section'))
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
app.add_config_value('latex_docclass', default_latex_docclass, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> None
app.setup_extension('sphinx.builders.html')
app.add_builder(EpubBuilder)
# config values
app.add_config_value('epub_basename', lambda self: make_filename(self.project), None)
app.add_config_value('epub_theme', 'epub', 'html')
app.add_config_value('epub_theme_options', {}, 'html')
app.add_config_value('epub_title', lambda self: self.html_title, 'html')
app.add_config_value('epub_author', 'unknown', 'html')
app.add_config_value('epub_language', lambda self: self.language or 'en', 'html')
app.add_config_value('epub_publisher', 'unknown', 'html')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'html')
app.add_config_value('epub_identifier', 'unknown', 'html')
app.add_config_value('epub_scheme', 'unknown', 'html')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'html')
app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'html')
def setup(app):
app.setup_extension("sphinx.builders.html")
app.add_builder(QtHelpBuilder)
app.add_config_value("qthelp_basename", lambda self: make_filename(self.project), None)
app.add_config_value("qthelp_theme", "nonav", "html")
app.add_config_value("qthelp_theme_options", {}, "html")
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(LaTeXBuilder)
app.add_post_transform(CitationReferenceTransform)
app.add_post_transform(MathReferenceTransform)
app.connect('config-inited', validate_config_values)
app.add_transform(FootnoteDocnameUpdater)
app.add_config_value('latex_engine', default_latex_engine, None,
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))
app.add_config_value('latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')],
None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_use_latex_multicolumn', False, None)
app.add_config_value('latex_use_xindy', default_latex_use_xindy, None)
app.add_config_value('latex_toplevel_sectioning', None, None,
ENUM(None, 'part', 'chapter', 'section'))
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
app.add_config_value('latex_docclass', default_latex_docclass, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.add_builder(ManualPageBuilder)
app.add_config_value(
'man_pages', lambda self:
[(self.master_doc, make_filename(self.project).lower(), '%s %s' %
(self.project, self.release), [], 1)], None)
app.add_config_value('man_show_urls', False, None)
def setup(app):
app.add_builder(ManualPageBuilder)
app.add_config_value('man_pages',
lambda self: [(self.master_doc, make_filename(self.project).lower(),
'%s %s' % (self.project, self.release), [], 1)],
None)
app.add_config_value('man_show_urls', False, None)
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(AppleHelpBuilder)
app.add_config_value('applehelp_bundle_name',
lambda self: make_filename(self.project), 'applehelp')
app.add_config_value('applehelp_bundle_id', None, 'applehelp',
string_classes)
app.add_config_value('applehelp_dev_region', 'en-us', 'applehelp')
app.add_config_value('applehelp_bundle_version', '1', 'applehelp')
app.add_config_value('applehelp_icon', None, 'applehelp', string_classes)
app.add_config_value(
'applehelp_kb_product', lambda self: '%s-%s' %
(make_filename(self.project), self.release), 'applehelp')
app.add_config_value('applehelp_kb_url', None, 'applehelp', string_classes)
app.add_config_value('applehelp_remote_url', None, 'applehelp',
string_classes)
app.add_config_value('applehelp_index_anchors', False, 'applehelp',
string_classes)
app.add_config_value('applehelp_min_term_length', None, 'applehelp',
string_classes)
app.add_config_value('applehelp_stopwords',
lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_locale',
lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_title',
lambda self: self.project + ' Help', 'applehelp')
app.add_config_value('applehelp_codesign_identity',
lambda self: environ.get('CODE_SIGN_IDENTITY', None),
'applehelp')
app.add_config_value(
'applehelp_codesign_flags',
lambda self: shlex.split(environ.get('OTHER_CODE_SIGN_FLAGS', '')),
'applehelp')
app.add_config_value('applehelp_indexer_path', '/usr/bin/hiutil',
'applehelp')
app.add_config_value('applehelp_codesign_path', '/usr/bin/codesign',
'applehelp')
app.add_config_value('applehelp_disable_external_tools', False, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> None
app.setup_extension('sphinx.builders.html')
app.add_builder(QtHelpBuilder)
app.add_config_value('qthelp_basename', lambda self: make_filename(self.project), None)
app.add_config_value('qthelp_theme', 'nonav', 'html')
app.add_config_value('qthelp_theme_options', {}, 'html')
def setup(app):
app.add_builder(TexinfoBuilder)
app.add_config_value(
'texinfo_documents', lambda self:
[(self.master_doc, make_filename(self.project).lower(), self.project,
'', make_filename(self.project), 'The %s reference manual.' %
make_filename(self.project), 'Python')], None)
app.add_config_value('texinfo_appendices', [], None)
app.add_config_value('texinfo_elements', {}, None)
app.add_config_value('texinfo_domain_indices', True, None, [list])
app.add_config_value('texinfo_show_urls', 'footnote', None)
app.add_config_value('texinfo_no_detailmenu', False, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.setup_extension('sphinx.builders.html')
app.add_builder(HTMLHelpBuilder)
app.add_config_value('htmlhelp_basename', lambda self: make_filename(self.project), None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.setup_extension('sphinx.builders.html')
app.add_builder(HTMLHelpBuilder)
app.add_config_value('htmlhelp_basename', lambda self: make_filename(self.project), None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app: Sphinx) -> Dict[str, Any]:
app.setup_extension('sphinx.builders.html')
app.add_builder(DevhelpBuilder)
app.add_message_catalog(__name__, path.join(package_dir, 'locales'))
app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
return {
'version': __version__,
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def _get_help_emissions(env, target, srcinfo, suffixes, basenameConfigKey='project'):
basename = make_filename(
srcinfo.config.get(basenameConfigKey, srcinfo.config['project']))
sources = []
sources.extend(srcinfo.sources)
sources.extend(srcinfo.templates)
sources.extend(srcinfo.statics)
targets = [target[0].File(basename + s) for s in suffixes]
return targets, sources
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(DevhelpBuilder)
app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(DevhelpBuilder)
app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(TexinfoBuilder)
app.add_config_value('texinfo_documents',
lambda self: [(self.master_doc, make_filename(self.project).lower(),
self.project, '', make_filename(self.project),
'The %s reference manual.' %
make_filename(self.project),
'Python')],
None)
app.add_config_value('texinfo_appendices', [], None)
app.add_config_value('texinfo_elements', {}, None)
app.add_config_value('texinfo_domain_indices', True, None, [list])
app.add_config_value('texinfo_show_urls', 'footnote', None)
app.add_config_value('texinfo_no_detailmenu', False, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.add_builder(ManualPageBuilder)
app.add_config_value(
'man_pages', lambda self:
[(self.master_doc, make_filename(self.project).lower(), '%s %s' %
(self.project, self.release), [], 1)], None)
app.add_config_value('man_show_urls', False, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(HTMLHelpBuilder)
app.add_config_value('htmlhelp_basename', lambda self: make_filename(self.project), None)
app.add_config_value('htmlhelp_file_suffix', None, 'html', string_classes)
app.add_config_value('htmlhelp_link_suffix', None, 'html', string_classes)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app: Sphinx) -> Dict[str, Any]:
app.setup_extension('sphinx.builders.html')
app.add_builder(AppleHelpBuilder)
app.add_message_catalog(__name__, path.join(package_dir, 'locales'))
app.add_config_value('applehelp_bundle_name',
lambda self: make_filename(self.project), 'applehelp')
app.add_config_value('applehelp_bundle_id', None, 'applehelp', [str])
app.add_config_value('applehelp_dev_region', 'en-us', 'applehelp')
app.add_config_value('applehelp_bundle_version', '1', 'applehelp')
app.add_config_value('applehelp_icon', None, 'applehelp', [str])
app.add_config_value('applehelp_kb_product',
lambda self: '%s-%s' % (make_filename(self.project), self.release),
'applehelp')
app.add_config_value('applehelp_kb_url', None, 'applehelp', [str])
app.add_config_value('applehelp_remote_url', None, 'applehelp', [str])
app.add_config_value('applehelp_index_anchors', False, 'applehelp', [str])
app.add_config_value('applehelp_min_term_length', None, 'applehelp', [str])
app.add_config_value('applehelp_stopwords',
lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_locale', lambda self: self.language or 'en', 'applehelp')
app.add_config_value('applehelp_title', lambda self: self.project + ' Help', 'applehelp')
app.add_config_value('applehelp_codesign_identity',
lambda self: environ.get('CODE_SIGN_IDENTITY', None),
'applehelp')
app.add_config_value('applehelp_codesign_flags',
lambda self: shlex.split(environ.get('OTHER_CODE_SIGN_FLAGS', '')),
'applehelp')
app.add_config_value('applehelp_indexer_path', '/usr/bin/hiutil', 'applehelp')
app.add_config_value('applehelp_codesign_path', '/usr/bin/codesign', 'applehelp')
app.add_config_value('applehelp_disable_external_tools', False, None)
return {
'version': __version__,
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(QtHelpBuilder)
app.add_config_value('qthelp_basename', lambda self: make_filename(self.project), None)
app.add_config_value('qthelp_namespace', None, 'html', string_classes)
app.add_config_value('qthelp_theme', 'nonav', 'html')
app.add_config_value('qthelp_theme_options', {}, 'html')
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(ManualPageBuilder)
app.add_config_value('man_pages',
lambda self: [(self.master_doc, make_filename(self.project).lower(),
'%s %s' % (self.project, self.release), [], 1)],
None)
app.add_config_value('man_show_urls', False, None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(QtHelpBuilder)
app.add_config_value('qthelp_basename', lambda self: make_filename(self.project), None)
app.add_config_value('qthelp_namespace', None, 'html', string_classes)
app.add_config_value('qthelp_theme', 'nonav', 'html')
app.add_config_value('qthelp_theme_options', {}, 'html')
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[str, Any]
app.add_builder(Epub3Builder)
# config values
app.add_config_value('epub_basename',
lambda self: make_filename(self.project), None)
app.add_config_value('epub_version', 3.0, 'epub') # experimental
app.add_config_value('epub_theme', 'epub', 'epub')
app.add_config_value('epub_theme_options', {}, 'epub')
app.add_config_value('epub_title', lambda self: self.project, 'epub')
app.add_config_value('epub_author', lambda self: self.author, 'epub')
app.add_config_value('epub_language', lambda self: self.language or 'en',
'epub')
app.add_config_value('epub_publisher', lambda self: self.author, 'epub')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'epub')
app.add_config_value('epub_identifier', 'unknown', 'epub')
app.add_config_value('epub_scheme', 'unknown', 'epub')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_css_files',
lambda config: config.html_css_files, 'epub')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'epub')
app.add_config_value('epub_use_index', lambda self: self.html_use_index,
'epub')
app.add_config_value('epub_description', 'unknown', 'epub')
app.add_config_value('epub_contributor', 'unknown', 'epub')
app.add_config_value('epub_writing_mode', 'horizontal', 'epub',
ENUM('horizontal', 'vertical'))
# event handlers
app.connect('config-inited', convert_epub_css_files)
app.connect('builder-inited', validate_config_values)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def default_docx_documents(conf):
start_doc = conf.master_doc
filename = '%s.docx' % make_filename(conf.project)
title = conf.project
# author configuration value is available from Sphinx 1.8
author = getattr(conf, 'author', 'sphinx-docxbuilder')
properties = {
'title': title,
'creator': author,
'subject': '',
'category': '',
'description': 'This document generaged by sphix-docxbuilder',
'keywords': ['python', 'Office Open XML', 'Word'],
}
toc_only = False
return [(start_doc, filename, properties, toc_only)]
def setup(app):
# type: (Sphinx) -> Dict[str, Any]
app.add_builder(Epub3Builder)
# config values
app.add_config_value('epub_basename', lambda self: make_filename(self.project), None)
app.add_config_value('epub_version', 3.0, 'epub') # experimental
app.add_config_value('epub_theme', 'epub', 'epub')
app.add_config_value('epub_theme_options', {}, 'epub')
app.add_config_value('epub_title', lambda self: self.project, 'epub')
app.add_config_value('epub_author', lambda self: self.author, 'epub')
app.add_config_value('epub_language', lambda self: self.language or 'en', 'epub')
app.add_config_value('epub_publisher', lambda self: self.author, 'epub')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'epub')
app.add_config_value('epub_identifier', 'unknown', 'epub')
app.add_config_value('epub_scheme', 'unknown', 'epub')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_css_files', lambda config: config.html_css_files, 'epub')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'epub')
app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'epub')
app.add_config_value('epub_description', 'unknown', 'epub')
app.add_config_value('epub_contributor', 'unknown', 'epub')
app.add_config_value('epub_writing_mode', 'horizontal', 'epub',
ENUM('horizontal', 'vertical'))
# event handlers
app.connect('config-inited', convert_epub_css_files)
app.connect('builder-inited', validate_config_values)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> None
app.add_builder(LaTeXBuilder)
app.connect('builder-inited', validate_config_values)
app.add_config_value('latex_engine',
lambda self: 'pdflatex' if self.language != 'ja' else 'platex',
None,
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))
app.add_config_value('latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')],
None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_keep_old_macro_names', True, None)
# now deprecated - use latex_toplevel_sectioning
app.add_config_value('latex_use_parts', False, None)
app.add_config_value('latex_toplevel_sectioning', None, None, [str])
app.add_config_value('latex_use_modindex', True, None) # deprecated
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
# paper_size and font_size are still separate values
# so that you can give them easily on the command line
app.add_config_value('latex_paper_size', 'letter', None)
app.add_config_value('latex_font_size', '10pt', None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
japanese_default = {'manual': 'jsbook',
'howto': 'jreport'}
app.add_config_value('latex_docclass',
lambda self: japanese_default if self.language == 'ja' else {},
None)
# now deprecated - use latex_elements
app.add_config_value('latex_preamble', '', None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_builder(LaTeXBuilder)
app.connect('builder-inited', validate_config_values)
app.add_config_value(
'latex_engine', lambda self: 'pdflatex'
if self.language != 'ja' else 'platex', None,
ENUM('pdflatex', 'xelatex', 'lualatex', 'platex'))
app.add_config_value(
'latex_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.tex',
self.project, '', 'manual')], None)
app.add_config_value('latex_logo', None, None, string_classes)
app.add_config_value('latex_appendices', [], None)
app.add_config_value('latex_keep_old_macro_names', True, None)
# now deprecated - use latex_toplevel_sectioning
app.add_config_value('latex_use_parts', False, None)
app.add_config_value('latex_toplevel_sectioning', None, None, [str])
app.add_config_value('latex_use_modindex', True, None) # deprecated
app.add_config_value('latex_domain_indices', True, None, [list])
app.add_config_value('latex_show_urls', 'no', None)
app.add_config_value('latex_show_pagerefs', False, None)
# paper_size and font_size are still separate values
# so that you can give them easily on the command line
app.add_config_value('latex_paper_size', 'letter', None)
app.add_config_value('latex_font_size', '10pt', None)
app.add_config_value('latex_elements', {}, None)
app.add_config_value('latex_additional_files', [], None)
japanese_default = {'manual': 'jsbook', 'howto': 'jreport'}
app.add_config_value(
'latex_docclass', lambda self: japanese_default
if self.language == 'ja' else {}, None)
# now deprecated - use latex_elements
app.add_config_value('latex_preamble', '', None)
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.add_config_value('mobi_basename',lambda self: make_filename(self.project), None)
app.add_config_value('mobi_theme','mobi', 'html')
app.add_config_value('mobi_title',lambda self: self.html_title, 'html')
app.add_config_value('mobi_author','unknown', 'html')
app.add_config_value('mobi_language',lambda self: self.language or 'en', 'html')
app.add_config_value('mobi_publisher','unknown', 'html')
app.add_config_value('mobi_copyright',lambda self: self.copyright, 'html')
app.add_config_value('mobi_identifier','unknown', 'html')
app.add_config_value('mobi_scheme','unknown', 'html')
app.add_config_value('mobi_uid','unknown', 'env')
app.add_config_value('mobi_cover',(), 'env')
app.add_config_value('mobi_pre_files',[], 'env')
app.add_config_value('mobi_post_files',[], 'env')
app.add_config_value('mobi_exclude_files',[], 'env')
app.add_config_value('mobi_tocdepth',3, 'env')
app.add_config_value('mobi_tocdup',True, 'env')
app.add_config_value('mobi_add_visible_links',True, 'env')
app.add_builder(MobiBuilder)
def _get_epub_emissions(env, target, srcinfo):
epubPreFiles = srcinfo.config.get('epub_pre_files', [])
epubPostFiles = srcinfo.config.get('epub_post_files', [])
epubCover = srcinfo.config.get('epub_cover', (None, None))
sources = []
sources.extend(srcinfo.sources)
sources.extend([srcinfo.srcroot.File(os_path(f[0])) for f in epubPreFiles])
sources.extend([srcinfo.srcroot.File(os_path(f[0])) for f in epubPostFiles])
if not (epubCover[0] is None or epubCover[0] == ''):
sources.append(srcinfo.srcroot.File(os_path(epubCover[0])))
if not (epubCover[1] is None or epubCover[1] == ''):
sources.append(srcinfo.srcroot.File(os_path(epubCover[1])))
t = srcinfo.config.get('epub_basename',
srcinfo.config.get('project',
'Python'))
targets = [target[0].File("%s.epub" % make_filename(t))]
return targets, sources
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(Epub2Builder)
app.connect('builder-inited', emit_deprecation_warning)
# config values
app.add_config_value('epub_basename',
lambda self: make_filename(self.project), None)
app.add_config_value('epub_theme', 'epub', 'html')
app.add_config_value('epub_theme_options', {}, 'html')
app.add_config_value('epub_title', lambda self: self.html_title, 'html')
app.add_config_value('epub_author', 'unknown', 'html')
app.add_config_value('epub_language', lambda self: self.language or 'en',
'html')
app.add_config_value('epub_publisher', 'unknown', 'html')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'html')
app.add_config_value('epub_identifier', 'unknown', 'html')
app.add_config_value('epub_scheme', 'unknown', 'html')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'html')
app.add_config_value('epub_use_index', lambda self: self.html_use_index,
'html')
return {
'version': 'builtin',
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
app.add_config_value('mobi_basename',
lambda self: make_filename(self.project), None)
app.add_config_value('mobi_theme', 'mobi', 'html')
app.add_config_value('mobi_title', lambda self: self.html_title, 'html')
app.add_config_value('mobi_author', 'unknown', 'html')
app.add_config_value('mobi_language', lambda self: self.language or 'en',
'html')
app.add_config_value('mobi_publisher', 'unknown', 'html')
app.add_config_value('mobi_copyright', lambda self: self.copyright, 'html')
app.add_config_value('mobi_identifier', 'unknown', 'html')
app.add_config_value('mobi_scheme', 'unknown', 'html')
app.add_config_value('mobi_uid', 'unknown', 'env')
app.add_config_value('mobi_cover', (), 'env')
app.add_config_value('mobi_pre_files', [], 'env')
app.add_config_value('mobi_post_files', [], 'env')
app.add_config_value('mobi_exclude_files', [], 'env')
app.add_config_value('mobi_tocdepth', 3, 'env')
app.add_config_value('mobi_tocdup', True, 'env')
app.add_config_value('mobi_add_visible_links', True, 'env')
app.add_builder(MobiBuilder)
def generate(d, overwrite=True, silent=False, templatedir=None):
# type: (Dict, bool, bool, str) -> None
"""Generate project based on values in *d*."""
template = QuickstartRenderer(templatedir=templatedir)
texescape.init()
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['PY3'] = True
d['project_fn'] = make_filename(d['project'])
d['project_url'] = quote(d['project'].encode('idna'))
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = column_width(d['project']) * '='
d.setdefault('extensions', [])
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = text_type(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = text_type(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped', 'author',
'author_texescaped', 'copyright', 'version', 'release',
'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
ensuredir(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
ensuredir(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
exclude_patterns = map(repr, [
d['dot'] + 'build',
'Thumbs.db',
'.DS_Store',
])
d['exclude_patterns'] = ', '.join(exclude_patterns)
ensuredir(builddir)
ensuredir(path.join(srcdir, d['dot'] + 'templates'))
ensuredir(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, content, newline=None):
# type: (str, str, str) -> None
if overwrite or not path.isfile(fpath):
if 'quiet' not in d:
print(__('Creating file %s.') % fpath)
with open(fpath, 'wt', encoding='utf-8', newline=newline) as f:
f.write(content)
else:
if 'quiet' not in d:
print(__('File %s already exists, skipping.') % fpath)
conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
if not conf_path or not path.isfile(conf_path):
conf_path = os.path.join(package_dir, 'templates', 'quickstart',
'conf.py_t')
with open(conf_path) as f:
conf_text = f.read()
write_file(path.join(srcdir, 'conf.py'),
template.render_string(conf_text, d))
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, template.render('quickstart/master_doc.rst_t', d))
if d.get('make_mode') is True:
makefile_template = 'quickstart/Makefile.new_t'
batchfile_template = 'quickstart/make.bat.new_t'
else:
makefile_template = 'quickstart/Makefile_t'
batchfile_template = 'quickstart/make.bat_t'
if d['makefile'] is True:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d['path'], 'Makefile'),
template.render(makefile_template, d), '\n')
if d['batchfile'] is True:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
write_file(path.join(d['path'], 'make.bat'),
template.render(batchfile_template, d), '\r\n')
if silent:
return
print()
print(
bold(__('Finished: An initial directory structure has been created.')))
print(
__('''
You should now populate your master file %s and create other documentation
source files. ''') % masterfile +
((d['makefile'] or d['batchfile']) and __('''\
Use the Makefile to build the docs, like so:
make builder
''') or __('''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''') % (srcdir, builddir)) + __('''\
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
'''))
class Config(object):
"""
Configuration file abstraction.
"""
# the values are: (default, what needs to be rebuilt if changed)
# If you add a value here, don't forget to include it in the
# quickstart.py file template as well as in the docs!
config_values = dict(
# general options
project=('Python', 'env'),
copyright=('', 'html'),
version=('', 'env'),
release=('', 'env'),
today=('', 'env'),
today_fmt=(None, 'env'), # the real default is locale-dependent
language=(None, 'env'),
locale_dirs=([], 'env'),
master_doc=('contents', 'env'),
source_suffix=(['.rst'], 'env'),
source_encoding=('utf-8-sig', 'env'),
source_parsers=({}, 'env'),
exclude_patterns=([], 'env'),
default_role=(None, 'env'),
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'),
highlight_options=({}, 'env'),
templates_path=([], 'html'),
template_bridge=(None, 'html'),
keep_warnings=(False, 'env'),
modindex_common_prefix=([], 'html'),
rst_epilog=(None, 'env'),
rst_prolog=(None, 'env'),
trim_doctest_flags=(True, 'env'),
primary_domain=('py', 'env'),
needs_sphinx=(None, None),
needs_extensions=({}, None),
nitpicky=(False, 'env'),
nitpick_ignore=([], 'html'),
numfig=(False, 'env'),
numfig_secnum_depth=(1, 'env'),
numfig_format=({
'figure': l_('Fig. %s'),
'table': l_('Table %s'),
'code-block': l_('Listing %s')
}, 'env'),
# HTML options
html_theme=('alabaster', 'html'),
html_theme_path=([], 'html'),
html_theme_options=({}, 'html'),
html_title=(lambda self: l_('%s %s documentation') %
(self.project, self.release), 'html'),
html_short_title=(lambda self: self.html_title, 'html'),
html_style=(None, 'html'),
html_logo=(None, 'html'),
html_favicon=(None, 'html'),
html_static_path=([], 'html'),
html_extra_path=([], 'html'),
# the real default is locale-dependent
html_last_updated_fmt=(None, 'html'),
html_use_smartypants=(True, 'html'),
html_translator_class=(None, 'html'),
html_sidebars=({}, 'html'),
html_additional_pages=({}, 'html'),
html_use_modindex=(True, 'html'), # deprecated
html_domain_indices=(True, 'html'),
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_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_options=({}, 'html'),
html_search_scorer=('', None),
html_scaled_image_link=(True, 'html'),
# HTML help only options
htmlhelp_basename=(lambda self: make_filename(self.project), None),
# Qt help only options
qthelp_basename=(lambda self: make_filename(self.project), None),
# Devhelp only options
devhelp_basename=(lambda self: make_filename(self.project), None),
# Apple help options
applehelp_bundle_name=(lambda self: make_filename(self.project),
'applehelp'),
applehelp_bundle_id=(None, 'applehelp'),
applehelp_dev_region=('en-us', 'applehelp'),
applehelp_bundle_version=('1', 'applehelp'),
applehelp_icon=(None, 'applehelp'),
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_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'),
applehelp_codesign_identity=(
lambda self: environ.get('CODE_SIGN_IDENTITY', None), 'applehelp'),
applehelp_codesign_flags=(
lambda self: shlex.split(environ.get('OTHER_CODE_SIGN_FLAGS', '')),
'applehelp'),
applehelp_indexer_path=('/usr/bin/hiutil', 'applehelp'),
applehelp_codesign_path=('/usr/bin/codesign', 'applehelp'),
applehelp_disable_external_tools=(False, None),
# Epub options
epub_basename=(lambda self: make_filename(self.project), None),
epub_theme=('epub', 'html'),
epub_theme_options=({}, 'html'),
epub_title=(lambda self: self.html_title, 'html'),
epub_author=('unknown', 'html'),
epub_language=(lambda self: self.language or 'en', 'html'),
epub_publisher=('unknown', 'html'),
epub_copyright=(lambda self: self.copyright, 'html'),
epub_identifier=('unknown', 'html'),
epub_scheme=('unknown', 'html'),
epub_uid=('unknown', 'env'),
epub_cover=((), 'env'),
epub_guide=((), 'env'),
epub_pre_files=([], 'env'),
epub_post_files=([], 'env'),
epub_exclude_files=([], 'env'),
epub_tocdepth=(3, 'env'),
epub_tocdup=(True, 'env'),
epub_tocscope=('default', 'env'),
epub_fix_images=(False, 'env'),
epub_max_image_width=(0, 'env'),
epub_show_urls=('inline', 'html'),
epub_use_index=(lambda self: self.html_use_index, 'html'),
# LaTeX options
latex_documents=(
lambda self: [(self.master_doc, make_filename(self.project) +
'.tex', self.project, '', 'manual')], None),
latex_logo=(None, None),
latex_appendices=([], None),
latex_use_parts=(False, None),
latex_use_modindex=(True, None), # deprecated
latex_domain_indices=(True, None),
latex_show_urls=('no', None),
latex_show_pagerefs=(False, None),
# paper_size and font_size are still separate values
# so that you can give them easily on the command line
latex_paper_size=('letter', None),
latex_font_size=('10pt', None),
latex_elements=({}, None),
latex_additional_files=([], None),
latex_docclass=({}, None),
# now deprecated - use latex_elements
latex_preamble=('', None),
# text options
text_sectionchars=('*=-~"+`', 'env'),
text_newlines=('unix', 'env'),
# manpage options
man_pages=(lambda self: [(self.master_doc, make_filename(
self.project).lower(), '%s %s' %
(self.project, self.release), [], 1)], None),
man_show_urls=(False, None),
# Texinfo options
texinfo_documents=(lambda self: [(
self.master_doc, make_filename(self.project).lower(), self.project,
'', make_filename(self.project), 'The %s reference manual.' %
make_filename(self.project), 'Python')], None),
texinfo_appendices=([], None),
texinfo_elements=({}, None),
texinfo_domain_indices=(True, None),
texinfo_show_urls=('footnote', None),
texinfo_no_detailmenu=(False, None),
# linkcheck options
linkcheck_ignore=([], None),
linkcheck_timeout=(None, None),
linkcheck_workers=(5, None),
linkcheck_anchors=(True, None),
# gettext options
gettext_compact=(True, 'gettext'),
gettext_location=(True, 'gettext'),
gettext_uuid=(False, 'gettext'),
gettext_auto_build=(True, 'env'),
gettext_additional_targets=([], 'env'),
# XML options
xml_pretty=(True, 'env'),
)
def __init__(self, dirname, filename, overrides, tags):
self.overrides = overrides
self.values = Config.config_values.copy()
config = {}
if 'extensions' in overrides: # XXX do we need this?
if isinstance(overrides['extensions'], string_types):
config['extensions'] = overrides.pop('extensions').split(',')
else:
config['extensions'] = overrides.pop('extensions')
if dirname is not None:
config_file = path.join(dirname, filename)
config['__file__'] = config_file
config['tags'] = tags
with cd(dirname):
# we promise to have the config dir as current dir while the
# config file is executed
try:
execfile_(filename, config)
except SyntaxError as err:
raise ConfigError(CONFIG_SYNTAX_ERROR % err)
except SystemExit:
raise ConfigError(CONFIG_EXIT_ERROR)
self._raw_config = config
# these two must be preinitialized because extensions can add their
# own config values
self.setup = config.get('setup', None)
self.extensions = config.get('extensions', [])
def check_types(self, warn):
# check all values for deviation from the default value's type, since
# that can result in TypeErrors all over the place
# 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:
continue # we don't know a default value
default, dummy_rebuild = Config.config_values[name]
if hasattr(default, '__call__'):
default = default(self) # could invoke l_()
if default is None:
continue
current = self[name]
if type(current) is type(default):
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__))
def check_unicode(self, warn):
# check all string values for non-ASCII characters in bytestrings,
# since that can result in UnicodeErrors all over the place
for name, value in iteritems(self._raw_config):
if isinstance(value, binary_type) and nonascii_re.search(value):
warn('the config value %r is set to a string with non-ASCII '
'characters; this can lead to Unicode errors occurring. '
'Please use Unicode strings, e.g. %r.' %
(name, u'Content'))
def init_values(self, warn):
config = self._raw_config
for valname, value in iteritems(self.overrides):
if '.' in valname:
realvalname, key = valname.split('.', 1)
config.setdefault(realvalname, {})[key] = value
continue
elif valname not in self.values:
warn('unknown config value %r in override, ignoring' % valname)
continue
defvalue = self.values[valname][0]
if isinstance(value, string_types):
if isinstance(defvalue, dict):
warn('cannot override dictionary config setting %r, '
'ignoring (use %r to set individual elements)' %
(valname, valname + '.key=value'))
continue
elif isinstance(defvalue, list):
config[valname] = value.split(',')
elif isinstance(defvalue, integer_types):
try:
config[valname] = int(value)
except ValueError:
warn(
'invalid number %r for config value %r, ignoring' %
(value, valname))
elif hasattr(defvalue, '__call__'):
config[valname] = value
elif defvalue is not None and not isinstance(
defvalue, string_types):
warn('cannot override config setting %r with unsupported '
'type, ignoring' % valname)
else:
config[valname] = value
else:
config[valname] = value
for name in config:
if name in self.values:
self.__dict__[name] = config[name]
if isinstance(self.source_suffix, string_types):
self.source_suffix = [self.source_suffix]
def __getattr__(self, name):
if name.startswith('_'):
raise AttributeError(name)
if name not in self.values:
raise AttributeError('No such config value: %s' % name)
default = self.values[name][0]
if hasattr(default, '__call__'):
return default(self)
return default
def __getitem__(self, name):
return getattr(self, name)
def __setitem__(self, name, value):
setattr(self, name, value)
def __delitem__(self, name):
delattr(self, name)
def __contains__(self, name):
return name in self.values
def setup(app):
# type: (Sphinx) -> None
app.setup_extension('sphinx.builders.html')
app.add_builder(DevhelpBuilder)
app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
def generate(d, overwrite=True, silent=False):
"""Generate project based on values in *d*."""
template = SphinxRenderer()
texescape.init()
indent = " " * 4
if "mastertoctree" not in d:
d["mastertoctree"] = ""
if "mastertocmaxdepth" not in d:
d["mastertocmaxdepth"] = 2
d["PY3"] = PY3
d["project_fn"] = make_filename(d["project"])
d["project_url"] = urlquote(d["project"].encode("idna"))
d["project_manpage"] = d["project_fn"].lower()
d["now"] = time.asctime()
d["project_underline"] = column_width(d["project"]) * "="
extensions = (",\n" + indent).join(repr("sphinx.ext." + name) for name in EXTENSIONS if d.get("ext_" + name))
if extensions:
d["extensions"] = "\n" + indent + extensions + ",\n"
else:
d["extensions"] = extensions
d["copyright"] = time.strftime("%Y") + ", " + d["author"]
d["author_texescaped"] = text_type(d["author"]).translate(texescape.tex_escape_map)
d["project_doc"] = d["project"] + " Documentation"
d["project_doc_texescaped"] = text_type(d["project"] + " Documentation").translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in (
"project",
"project_doc",
"project_doc_texescaped",
"author",
"author_texescaped",
"copyright",
"version",
"release",
"master",
):
d[key + "_str"] = d[key].replace("\\", "\\\\").replace("'", "\\'")
if not path.isdir(d["path"]):
mkdir_p(d["path"])
srcdir = d["sep"] and path.join(d["path"], "source") or d["path"]
mkdir_p(srcdir)
if d["sep"]:
builddir = path.join(d["path"], "build")
d["exclude_patterns"] = ""
else:
builddir = path.join(srcdir, d["dot"] + "build")
exclude_patterns = map(repr, [d["dot"] + "build", "Thumbs.db", ".DS_Store"])
d["exclude_patterns"] = ", ".join(exclude_patterns)
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d["dot"] + "templates"))
mkdir_p(path.join(srcdir, d["dot"] + "static"))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print("Creating file %s." % fpath)
with open(fpath, "wt", encoding="utf-8", newline=newline) as f:
f.write(content)
else:
print("File %s already exists, skipping." % fpath)
with open(os.path.join(package_dir, "templates", "quickstart", "conf.py_t")) as f:
conf_text = convert_python_source(f.read())
write_file(path.join(srcdir, "conf.py"), template.render_string(conf_text, d))
masterfile = path.join(srcdir, d["master"] + d["suffix"])
write_file(masterfile, template.render("quickstart/master_doc.rst_t", d))
if d.get("make_mode") is True:
makefile_template = "quickstart/Makefile.new_t"
batchfile_template = "quickstart/make.bat.new_t"
else:
makefile_template = "quickstart/Makefile_t"
batchfile_template = "quickstart/make.bat_t"
if d["makefile"] is True:
d["rsrcdir"] = d["sep"] and "source" or "."
d["rbuilddir"] = d["sep"] and "build" or d["dot"] + "build"
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d["path"], "Makefile"), template.render(makefile_template, d), u"\n")
if d["batchfile"] is True:
d["rsrcdir"] = d["sep"] and "source" or "."
d["rbuilddir"] = d["sep"] and "build" or d["dot"] + "build"
write_file(path.join(d["path"], "make.bat"), template.render(batchfile_template, d), u"\r\n")
if silent:
return
print()
print(bold("Finished: An initial directory structure has been created."))
print(
"""
You should now populate your master file %s and create other documentation
source files. """
% masterfile
+ (
(d["makefile"] or d["batchfile"])
and """\
Use the Makefile to build the docs, like so:
make builder
"""
or """\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
"""
% (srcdir, builddir)
)
+ """\
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
"""
)
def generate(d, overwrite=True, silent=False):
"""Generate project based on values in *d*."""
texescape.init()
indent = ' ' * 4
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = column_width(d['project']) * '='
extensions = (',\n' + indent).join(
repr('sphinx.ext.' + name)
for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
'pngmath', 'mathjax', 'ifconfig', 'viewcode')
if d.get('ext_' + name))
if extensions:
d['extensions'] = '\n' + indent + extensions + ',\n'
else:
d['extensions'] = extensions
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = unicode(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped', 'author',
'author_texescaped', 'copyright', 'version', 'release',
'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_patterns'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print 'Creating file %s.' % fpath
f = open(fpath, 'wt', encoding='utf-8', newline=newline)
try:
f.write(content)
finally:
f.close()
else:
print 'File %s already exists, skipping.' % fpath
conf_text = QUICKSTART_CONF % d
if d['epub']:
conf_text += EPUB_CONFIG % d
if d.get('ext_intersphinx'):
conf_text += INTERSPHINX_CONFIG
write_file(path.join(srcdir, 'conf.py'), conf_text)
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, MASTER_FILE % d)
if d['makefile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d['path'], 'Makefile'), MAKEFILE % d, u'\n')
if d['batchfile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
write_file(path.join(d['path'], 'make.bat'), BATCHFILE % d, u'\r\n')
if silent:
return
print
print bold('Finished: An initial directory structure has been created.')
print '''
You should now populate your master file %s and create other documentation
source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
def generate(d, overwrite=True, silent=False):
"""
Borrowed from Sphinx 1.3b3.
Generate project based on values in *d*.
"""
texescape.init()
if "mastertoctree" not in d:
d["mastertoctree"] = ""
if "mastertocmaxdepth" not in d:
d["mastertocmaxdepth"] = 2
d["project_fn"] = make_filename(d["project"])
d["project_manpage"] = d["project_fn"].lower()
d["now"] = time.asctime()
d["project_underline"] = column_width(d["project"]) * "="
d["copyright"] = time.strftime("%Y") + ", " + d["author"]
d["author_texescaped"] = texescape.escape(
str(d["author"]).translate(str(d["author"])))
d["project_doc"] = d["project"] + " Documentation"
d["project_doc_texescaped"] = texescape.escape(
str(d["project"] + " Documentation").translate(
str(d["project"] + " Documentation")))
if not path.isdir(d["path"]):
ensuredir(d["path"])
srcdir = d["sep"] and path.join(d["path"], "source") or d["path"]
ensuredir(srcdir)
d["exclude_patterns"] = ""
# TODO: Work if we want this.
# if d['sep']:
# builddir = path.join(d['path'], 'build')
#
# else:
# builddir = path.join(srcdir, d['dot'] + 'build')
# d['exclude_patterns'] = repr(d['dot'] + 'build')
# ensuredir(builddir)
ensuredir(path.join(srcdir, d["dot"] + "templates"))
ensuredir(path.join(srcdir, d["dot"] + "static"))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print(f"Creating file {fpath}.")
f = open(fpath, "wt", encoding="utf-8", newline=newline)
try:
f.write(content)
finally:
f.close()
else:
print(f"File {fpath} already exists, skipping.")
conf_text = ABLOG_CONF.format(**d)
write_file(path.join(srcdir, "conf.py"), conf_text)
masterfile = path.join(srcdir, d["master"] + d["suffix"])
write_file(masterfile, ABLOG_INDEX.format(**d))
about = path.join(srcdir, "about" + d["suffix"])
write_file(about, ABLOG_ABOUT.format(**d))
d["post_date"] = datetime.datetime.today().strftime("%b %d, %Y")
firstpost = path.join(srcdir, "first-post" + d["suffix"])
write_file(firstpost, ABLOG_POST.format(**d))
if silent:
return
print(bold("Finished: An initial directory structure has been created."))
def generate(d, overwrite=True, silent=False):
"""Generate project based on values in *d*."""
texescape.init()
indent = " " * 4
if "mastertoctree" not in d:
d["mastertoctree"] = ""
if "mastertocmaxdepth" not in d:
d["mastertocmaxdepth"] = 2
d["project_fn"] = make_filename(d["project"])
d["project_manpage"] = d["project_fn"].lower()
d["now"] = time.asctime()
d["project_underline"] = len(d["project"]) * "="
extensions = (",\n" + indent).join(
repr("sphinx.ext." + name)
for name in (
"autodoc",
"doctest",
"intersphinx",
"todo",
"coverage",
"pngmath",
"mathjax",
"ifconfig",
"viewcode",
)
if d.get("ext_" + name)
)
if extensions:
d["extensions"] = "\n" + indent + extensions + ",\n"
else:
d["extensions"] = extensions
d["copyright"] = time.strftime("%Y") + ", " + d["author"]
d["author_texescaped"] = unicode(d["author"]).translate(texescape.tex_escape_map)
d["project_doc"] = d["project"] + " Documentation"
d["project_doc_texescaped"] = unicode(d["project"] + " Documentation").translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in (
"project",
"project_doc",
"project_doc_texescaped",
"author",
"author_texescaped",
"copyright",
"version",
"release",
"master",
):
d[key + "_str"] = d[key].replace("\\", "\\\\").replace("'", "\\'")
if not path.isdir(d["path"]):
mkdir_p(d["path"])
srcdir = d["sep"] and path.join(d["path"], "source") or d["path"]
mkdir_p(srcdir)
if d["sep"]:
builddir = path.join(d["path"], "build")
d["exclude_patterns"] = ""
else:
builddir = path.join(srcdir, d["dot"] + "build")
d["exclude_patterns"] = repr(d["dot"] + "build")
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d["dot"] + "templates"))
mkdir_p(path.join(srcdir, d["dot"] + "static"))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print "Creating file %s." % fpath
f = open(fpath, "wt", encoding="utf-8", newline=newline)
try:
f.write(content)
finally:
f.close()
else:
print "File %s already exists, skipping." % fpath
conf_text = QUICKSTART_CONF % d
if d["epub"]:
conf_text += EPUB_CONFIG % d
if d.get("ext_intersphinx"):
conf_text += INTERSPHINX_CONFIG
write_file(path.join(srcdir, "conf.py"), conf_text)
masterfile = path.join(srcdir, d["master"] + d["suffix"])
write_file(masterfile, MASTER_FILE % d)
if d["makefile"]:
d["rsrcdir"] = d["sep"] and "source" or "."
d["rbuilddir"] = d["sep"] and "build" or d["dot"] + "build"
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d["path"], "Makefile"), MAKEFILE % d, u"\n")
if d["batchfile"]:
d["rsrcdir"] = d["sep"] and "source" or "."
d["rbuilddir"] = d["sep"] and "build" or d["dot"] + "build"
write_file(path.join(d["path"], "make.bat"), BATCHFILE % d, u"\r\n")
if silent:
return
print
print bold("Finished: An initial directory structure has been created.")
print """
You should now populate your master file %s and create other documentation
source files. """ % masterfile + (
(d["makefile"] or d["batchfile"])
and """\
Use the Makefile to build the docs, like so:
make builder
"""
or """\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
"""
% (srcdir, builddir)
) + """\
def inner_main(args):
d = {}
texescape.init()
if not color_terminal():
nocolor()
print bold('Welcome to the Sphinx %s quickstart utility.') % __version__
print '''
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).'''
print '''
Enter the root path for documentation.'''
do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
while path.isfile(path.join(d['path'], 'conf.py')) or \
path.isfile(path.join(d['path'], 'source', 'conf.py')):
print
print bold('Error: an existing conf.py has been found in the '
'selected root path.')
print 'sphinx-quickstart will not overwrite existing Sphinx projects.'
print
do_prompt(d, 'path', 'Please enter a new root path (or just Enter '
'to exit)', '', is_path)
if not d['path']:
sys.exit(1)
print '''
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.'''
do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n',
boolean)
print '''
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.'''
do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok)
print '''
The project name will occur in several places in the built documentation.'''
do_prompt(d, 'project', 'Project name')
do_prompt(d, 'author', 'Author name(s)')
print '''
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.'''
do_prompt(d, 'version', 'Project version')
do_prompt(d, 'release', 'Project release', d['version'])
print '''
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.'''
do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix)
print '''
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.'''
do_prompt(d, 'master', 'Name of your master document (without suffix)',
'index')
while path.isfile(path.join(d['path'], d['master']+d['suffix'])) or \
path.isfile(path.join(d['path'], 'source', d['master']+d['suffix'])):
print
print bold('Error: the master file %s has already been found in the '
'selected root path.' % (d['master']+d['suffix']))
print 'sphinx-quickstart will not overwrite the existing file.'
print
do_prompt(d, 'master', 'Please enter a new file name, or rename the '
'existing file and press Enter', d['master'])
print '''
Sphinx can also add configuration for epub output:'''
do_prompt(d, 'epub', 'Do you want to use the epub builder (y/N)',
'n', boolean)
print '''
Please indicate if you want to use one of the following Sphinx extensions:'''
do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings '
'from modules (y/N)', 'n', boolean)
do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets '
'in doctest blocks (y/N)', 'n', boolean)
do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx '
'documentation of different projects (y/N)', 'n', boolean)
do_prompt(d, 'ext_todo', 'todo: write "todo" entries '
'that can be shown or hidden on build (y/N)', 'n', boolean)
do_prompt(d, 'ext_coverage', 'coverage: checks for documentation '
'coverage (y/N)', 'n', boolean)
do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered '
'as PNG images (y/N)', 'n', boolean)
do_prompt(d, 'ext_jsmath', 'jsmath: include math, rendered in the '
'browser by JSMath (y/N)', 'n', boolean)
if d['ext_pngmath'] and d['ext_jsmath']:
print '''Note: pngmath and jsmath cannot be enabled at the same time.
pngmath has been deselected.'''
do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of '
'content based on config values (y/N)', 'n', boolean)
do_prompt(d, 'ext_viewcode', 'viewcode: include links to the source code '
'of documented Python objects (y/N)', 'n', boolean)
print '''
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.'''
do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean)
do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)',
'y', boolean)
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['underline'] = len(d['project']) * '='
d['extensions'] = ', '.join(
repr('sphinx.ext.' + name)
for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
'pngmath', 'jsmath', 'ifconfig', 'viewcode')
if d['ext_' + name])
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = unicode(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'copyright', 'author', 'author_texescaped',
'project_doc_texescaped', 'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_patterns'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
conf_text = QUICKSTART_CONF % d
if d['epub']:
conf_text += EPUB_CONFIG % d
if d['ext_intersphinx']:
conf_text += INTERSPHINX_CONFIG
f = open(path.join(srcdir, 'conf.py'), 'w')
f.write(conf_text.encode('utf-8'))
f.close()
masterfile = path.join(srcdir, d['master'] + d['suffix'])
f = open(masterfile, 'w')
f.write((MASTER_FILE % d).encode('utf-8'))
f.close()
if d['makefile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
f = open(path.join(d['path'], 'Makefile'), 'wb')
f.write((MAKEFILE % d).encode('utf-8'))
f.close()
if d['batchfile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
f = open(path.join(d['path'], 'make.bat'), 'w')
f.write((BATCHFILE % d).encode('utf-8'))
f.close()
print
print bold('Finished: An initial directory structure has been created.')
print '''
You should now populate your master file %s and create other documentation
source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
def setup(app):
app.add_builder(SATySFiBuilder)
app.add_config_value(
'satisfy_documents',
lambda self: [(self.master_doc, make_filename(self.project) + '.saty',
self.project, '')], None)
def generate(d, overwrite=True, silent=False):
'''Borrowed from Sphinx 1.3b3'''
"""Generate project based on values in *d*."""
texescape.init()
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = column_width(d['project']) * '='
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = text_type(d['author']).translate(
texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = text_type(d['project'] +
' Documentation').translate(
texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped', 'author',
'author_texescaped', 'copyright', 'version', 'release',
'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
ensuredir(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
ensuredir(srcdir)
d['exclude_patterns'] = ''
# TODO: Work if we want this.
# if d['sep']:
# builddir = path.join(d['path'], 'build')
#
# else:
# builddir = path.join(srcdir, d['dot'] + 'build')
# d['exclude_patterns'] = repr(d['dot'] + 'build')
# ensuredir(builddir)
ensuredir(path.join(srcdir, d['dot'] + 'templates'))
ensuredir(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print('Creating file %s.' % fpath)
f = open(fpath, 'wt', encoding='utf-8', newline=newline)
try:
f.write(content)
finally:
f.close()
else:
print('File %s already exists, skipping.' % fpath)
conf_text = ABLOG_CONF % d
write_file(path.join(srcdir, 'conf.py'), conf_text)
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, ABLOG_INDEX % d)
about = path.join(srcdir, 'about' + d['suffix'])
write_file(about, ABLOG_ABOUT % d)
d['post_date'] = datetime.datetime.today().strftime('%b %d, %Y')
firstpost = path.join(srcdir, 'first-post' + d['suffix'])
write_file(firstpost, ABLOG_POST % d)
if silent:
return
print(bold('Finished: An initial directory structure has been created.'))
def inner_main(args):
d = {}
texescape.init()
if not color_terminal():
nocolor()
if len(args) > 3:
print 'Usage: sphinx-quickstart [root]'
sys.exit(1)
elif len(args) == 2:
d['path'] = args[1]
print bold('Welcome to the Sphinx %s quickstart utility.') % __version__
print '''
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).'''
if 'path' in d:
print bold('''
Selected root path: %s''' % d['path'])
else:
print '''
Enter the root path for documentation.'''
do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
while path.isfile(path.join(d['path'], 'conf.py')) or \
path.isfile(path.join(d['path'], 'source', 'conf.py')):
print
print bold('Error: an existing conf.py has been found in the '
'selected root path.')
print 'sphinx-quickstart will not overwrite existing Sphinx projects.'
print
do_prompt(d, 'path', 'Please enter a new root path (or just Enter '
'to exit)', '', is_path)
if not d['path']:
sys.exit(1)
print '''
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.'''
do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n',
boolean)
print '''
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.'''
do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok)
print '''
The project name will occur in several places in the built documentation.'''
do_prompt(d, 'project', 'Project name')
do_prompt(d, 'author', 'Author name(s)')
print '''
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.'''
do_prompt(d, 'version', 'Project version')
do_prompt(d, 'release', 'Project release', d['version'])
print '''
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.'''
do_prompt(d, 'suffix', 'Source file suffix', '.rst', suffix)
print '''
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.'''
do_prompt(d, 'master', 'Name of your master document (without suffix)',
'index')
while path.isfile(path.join(d['path'], d['master']+d['suffix'])) or \
path.isfile(path.join(d['path'], 'source', d['master']+d['suffix'])):
print
print bold('Error: the master file %s has already been found in the '
'selected root path.' % (d['master'] + d['suffix']))
print 'sphinx-quickstart will not overwrite the existing file.'
print
do_prompt(
d, 'master', 'Please enter a new file name, or rename the '
'existing file and press Enter', d['master'])
print '''
Sphinx can also add configuration for epub output:'''
do_prompt(d, 'epub', 'Do you want to use the epub builder (y/N)', 'n',
boolean)
print '''
Please indicate if you want to use one of the following Sphinx extensions:'''
do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings '
'from modules (y/N)', 'n', boolean)
do_prompt(
d, 'ext_doctest', 'doctest: automatically test code snippets '
'in doctest blocks (y/N)', 'n', boolean)
do_prompt(
d, 'ext_intersphinx', 'intersphinx: link between Sphinx '
'documentation of different projects (y/N)', 'n', boolean)
do_prompt(
d, 'ext_todo', 'todo: write "todo" entries '
'that can be shown or hidden on build (y/N)', 'n', boolean)
do_prompt(d, 'ext_coverage', 'coverage: checks for documentation '
'coverage (y/N)', 'n', boolean)
do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered '
'as PNG images (y/N)', 'n', boolean)
do_prompt(
d, 'ext_jsmath', 'jsmath: include math, rendered in the '
'browser by JSMath (y/N)', 'n', boolean)
if d['ext_pngmath'] and d['ext_jsmath']:
print '''Note: pngmath and jsmath cannot be enabled at the same time.
pngmath has been deselected.'''
do_prompt(
d, 'ext_ifconfig', 'ifconfig: conditional inclusion of '
'content based on config values (y/N)', 'n', boolean)
do_prompt(
d, 'ext_viewcode', 'viewcode: include links to the source code '
'of documented Python objects (y/N)', 'n', boolean)
print '''
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.'''
do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean)
do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', 'y',
boolean)
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['underline'] = len(d['project']) * '='
d['extensions'] = ', '.join(
repr('sphinx.ext.' + name)
for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
'pngmath', 'jsmath', 'ifconfig', 'viewcode')
if d['ext_' + name])
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = unicode(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'copyright', 'author', 'author_texescaped',
'project_doc_texescaped', 'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_patterns'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
conf_text = QUICKSTART_CONF % d
if d['epub']:
conf_text += EPUB_CONFIG % d
if d['ext_intersphinx']:
conf_text += INTERSPHINX_CONFIG
f = open(path.join(srcdir, 'conf.py'), 'w', encoding='utf-8')
f.write(conf_text)
f.close()
masterfile = path.join(srcdir, d['master'] + d['suffix'])
f = open(masterfile, 'w', encoding='utf-8')
f.write(MASTER_FILE % d)
f.close()
if d['makefile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
f = open(path.join(d['path'], 'Makefile'), 'wb', encoding='utf-8')
f.write(MAKEFILE % d)
f.close()
if d['batchfile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
f = open(path.join(d['path'], 'make.bat'), 'w', encoding='utf-8')
f.write(BATCHFILE % d)
f.close()
print
print bold('Finished: An initial directory structure has been created.')
print '''
You should now populate your master file %s and create other documentation
source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
class Config(object):
"""
Configuration file abstraction.
"""
# the values are: (default, what needs to be rebuilt if changed)
# If you add a value here, don't forget to include it in the
# quickstart.py file template as well as in the docs!
config_values = dict(
# general options
project=('Python', 'env'),
copyright=('', 'html'),
version=('', 'env'),
release=('', 'env'),
today=('', 'env'),
today_fmt=(None, 'env'), # the real default is locale-dependent
language=(None, 'env'),
locale_dirs=([], 'env'),
master_doc=('contents', 'env'),
source_suffix=('.rst', 'env'),
source_encoding=('utf-8-sig', 'env'),
exclude_patterns=([], 'env'),
# the next three are all deprecated now
unused_docs=([], 'env'),
exclude_trees=([], 'env'),
exclude_dirnames=([], 'env'),
default_role=(None, 'env'),
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'),
templates_path=([], 'html'),
template_bridge=(None, 'html'),
keep_warnings=(False, 'env'),
modindex_common_prefix=([], 'html'),
rst_epilog=(None, 'env'),
rst_prolog=(None, 'env'),
trim_doctest_flags=(True, 'env'),
primary_domain=('py', 'env'),
needs_sphinx=(None, None),
nitpicky=(False, 'env'),
nitpick_ignore=([], 'env'),
# HTML options
html_theme=('default', 'html'),
html_theme_path=([], 'html'),
html_theme_options=({}, 'html'),
html_title=(lambda self: l_('%s %s documentation') %
(self.project, self.release), 'html'),
html_short_title=(lambda self: self.html_title, 'html'),
html_style=(None, 'html'),
html_logo=(None, 'html'),
html_favicon=(None, 'html'),
html_static_path=([], 'html'),
# the real default is locale-dependent
html_last_updated_fmt=(None, 'html'),
html_use_smartypants=(True, 'html'),
html_translator_class=(None, 'html'),
html_sidebars=({}, 'html'),
html_additional_pages=({}, 'html'),
html_use_modindex=(True, 'html'), # deprecated
html_domain_indices=(True, 'html'),
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_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_options=({}, 'html'),
# HTML help only options
htmlhelp_basename=(lambda self: make_filename(self.project), None),
# Qt help only options
qthelp_basename=(lambda self: make_filename(self.project), None),
# Devhelp only options
devhelp_basename=(lambda self: make_filename(self.project), None),
# Epub options
epub_basename=(lambda self: make_filename(self.project), None),
epub_theme=('epub', 'html'),
epub_title=(lambda self: self.html_title, 'html'),
epub_author=('unknown', 'html'),
epub_language=(lambda self: self.language or 'en', 'html'),
epub_publisher=('unknown', 'html'),
epub_copyright=(lambda self: self.copyright, 'html'),
epub_identifier=('unknown', 'html'),
epub_scheme=('unknown', 'html'),
epub_uid=('unknown', 'env'),
epub_cover=((), 'env'),
epub_pre_files=([], 'env'),
epub_post_files=([], 'env'),
epub_exclude_files=([], 'env'),
epub_tocdepth=(3, 'env'),
epub_tocdup=(True, 'env'),
# LaTeX options
latex_documents=([], None),
latex_logo=(None, None),
latex_appendices=([], None),
latex_use_parts=(False, None),
latex_use_modindex=(True, None), # deprecated
latex_domain_indices=(True, None),
latex_show_urls=('no', None),
latex_show_pagerefs=(False, None),
# paper_size and font_size are still separate values
# so that you can give them easily on the command line
latex_paper_size=('letter', None),
latex_font_size=('10pt', None),
latex_elements=({}, None),
latex_additional_files=([], None),
latex_docclass=({}, None),
# now deprecated - use latex_elements
latex_preamble=('', None),
# text options
text_sectionchars=('*=-~"+`', 'env'),
text_newlines=('unix', 'env'),
# manpage options
man_pages=([], None),
man_show_urls=(False, None),
# Texinfo options
texinfo_documents=([], None),
texinfo_appendices=([], None),
texinfo_elements=({}, None),
texinfo_domain_indices=(True, None),
texinfo_show_urls=('footnote', None),
# linkcheck options
linkcheck_ignore=([], None),
linkcheck_timeout=(None, None),
linkcheck_workers=(5, None),
# gettext options
gettext_compact=(True, 'gettext'),
)
def __init__(self, dirname, filename, overrides, tags):
self.overrides = overrides
self.values = Config.config_values.copy()
config = {}
if dirname is not None:
config_file = path.join(dirname, filename)
config['__file__'] = config_file
config['tags'] = tags
olddir = os.getcwd()
try:
# we promise to have the config dir as current dir while the
# config file is executed
os.chdir(dirname)
# get config source -- 'b' is a no-op under 2.x, while 'U' is
# ignored under 3.x (but 3.x compile() accepts \r\n newlines)
f = open(config_file, 'rbU')
try:
source = f.read()
finally:
f.close()
try:
# compile to a code object, handle syntax errors
try:
code = compile(source, config_file, 'exec')
except SyntaxError:
if convert_with_2to3:
# maybe the file uses 2.x syntax; try to refactor to
# 3.x syntax using 2to3
source = convert_with_2to3(config_file)
code = compile(source, config_file, 'exec')
else:
raise
exec code in config
except SyntaxError, err:
raise ConfigError(CONFIG_SYNTAX_ERROR % err)
finally:
os.chdir(olddir)
self._raw_config = config
# these two must be preinitialized because extensions can add their
# own config values
self.setup = config.get('setup', None)
self.extensions = config.get('extensions', [])
def check_unicode(self, warn):
# check all string values for non-ASCII characters in bytestrings,
# since that can result in UnicodeErrors all over the place
for name, value in self._raw_config.iteritems():
if isinstance(value, bytes) and nonascii_re.search(value):
warn('the config value %r is set to a string with non-ASCII '
'characters; this can lead to Unicode errors occurring. '
'Please use Unicode strings, e.g. %r.' %
(name, u'Content'))
def init_values(self):
config = self._raw_config
for valname, value in self.overrides.iteritems():
if '.' in valname:
realvalname, key = valname.split('.', 1)
config.setdefault(realvalname, {})[key] = value
else:
config[valname] = value
for name in config:
if name in self.values:
self.__dict__[name] = config[name]
del self._raw_config
def __getattr__(self, name):
if name.startswith('_'):
raise AttributeError(name)
if name not in self.values:
raise AttributeError('No such config value: %s' % name)
default = self.values[name][0]
if hasattr(default, '__call__'):
return default(self)
return default
def __getitem__(self, name):
return getattr(self, name)
def __setitem__(self, name, value):
setattr(self, name, value)
def __delitem__(self, name):
delattr(self, name)
def __contains__(self, name):
return name in self.values
def generate(d, overwrite=True, silent=False):
"""Generate project based on values in *d*."""
texescape.init()
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = len(d['project']) * '='
d['extensions'] = ', '.join(
repr('sphinx.ext.' + name)
for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage',
'pngmath', 'mathjax', 'ifconfig', 'viewcode')
if d.get('ext_' + name))
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = unicode(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped',
'author', 'author_texescaped', 'copyright',
'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_patterns'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, mode, content):
if overwrite or not path.isfile(fpath):
print 'Creating file %s.' % fpath
f = open(fpath, mode, encoding='utf-8')
try:
f.write(content)
finally:
f.close()
else:
print 'File %s already exists, skipping.' % fpath
conf_text = QUICKSTART_CONF % d
if d['epub']:
conf_text += EPUB_CONFIG % d
if d.get('ext_intersphinx'):
conf_text += INTERSPHINX_CONFIG
write_file(path.join(srcdir, 'conf.py'), 'w', conf_text)
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, 'w', MASTER_FILE % d)
if d['makefile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d['path'], 'Makefile'), 'wb', MAKEFILE % d)
if d['batchfile']:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
write_file(path.join(d['path'], 'make.bat'), 'w', BATCHFILE % d)
if silent:
return
print
print bold('Finished: An initial directory structure has been created.')
print '''
You should now populate your master file %s and create other documentation
source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True
# ------------------------------------------------------------------------------
# Since loadConfig overwrites settings from the global namespace, it has to be
# the last statement in the conf.py file
# ------------------------------------------------------------------------------
loadConfig(globals())
if not 'latex_documents' in globals():
# (startdocname, targetname, title, author, documentclass, toctree_only)
latex_documents = [
(master_doc, make_filename(project) + '.tex', project, '', os.environ.get("DOCCLASS", "report"), False)
]
else:
mem = latex_documents
latex_documents = []
for entry in mem:
entry = list(entry)
entry[4] = os.environ.get("DOCCLASS", "report")
latex_documents.append(tuple(entry))
def setup(app):
app.setup_extension('sphinx.builders.html')
app.add_builder(HTMLHelpBuilder)
app.add_config_value('htmlhelp_basename', lambda self: make_filename(self.project), None)
def generate(d, overwrite=True, silent=False, templatedir=None):
# type: (Dict, bool, bool, unicode) -> None
"""Generate project based on values in *d*."""
template = QuickstartRenderer(templatedir=templatedir)
texescape.init()
indent = ' ' * 4
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['PY3'] = PY3
d['project_fn'] = make_filename(d['project'])
d['project_url'] = urlquote(d['project'].encode('idna'))
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = column_width(d['project']) * '='
d.setdefault('extensions', [])
for name in EXTENSIONS:
if d.get('ext_' + name):
d['extensions'].append('sphinx.ext.' + name)
d['extensions'] = (',\n' + indent).join(repr(name) for name in d['extensions'])
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = text_type(d['author']).\
translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = text_type(d['project'] + ' Documentation').\
translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped',
'author', 'author_texescaped', 'copyright',
'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
ensuredir(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
ensuredir(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
exclude_patterns = map(repr, [
d['dot'] + 'build',
'Thumbs.db', '.DS_Store',
])
d['exclude_patterns'] = ', '.join(exclude_patterns)
ensuredir(builddir)
ensuredir(path.join(srcdir, d['dot'] + 'templates'))
ensuredir(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, content, newline=None):
# type: (unicode, unicode, unicode) -> None
if overwrite or not path.isfile(fpath):
if 'quiet' not in d:
print('Creating file %s.' % fpath)
with open(fpath, 'wt', encoding='utf-8', newline=newline) as f:
f.write(content)
else:
if 'quiet' not in d:
print('File %s already exists, skipping.' % fpath)
conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
if not conf_path or not path.isfile(conf_path):
conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')
with open(conf_path) as f:
conf_text = convert_python_source(f.read())
write_file(path.join(srcdir, 'conf.py'), template.render_string(conf_text, d))
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, template.render('quickstart/master_doc.rst_t', d))
if d.get('make_mode') is True:
makefile_template = 'quickstart/Makefile.new_t'
batchfile_template = 'quickstart/make.bat.new_t'
else:
makefile_template = 'quickstart/Makefile_t'
batchfile_template = 'quickstart/make.bat_t'
if d['makefile'] is True:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
# use binary mode, to avoid writing \r\n on Windows
write_file(path.join(d['path'], 'Makefile'),
template.render(makefile_template, d), u'\n')
if d['batchfile'] is True:
d['rsrcdir'] = d['sep'] and 'source' or '.'
d['rbuilddir'] = d['sep'] and 'build' or d['dot'] + 'build'
write_file(path.join(d['path'], 'make.bat'),
template.render(batchfile_template, d), u'\r\n')
if silent:
return
print()
print(bold('Finished: An initial directory structure has been created.'))
print('''
You should now populate your master file %s and create other documentation
source files. ''' % masterfile + ((d['makefile'] or d['batchfile']) and '''\
Use the Makefile to build the docs, like so:
make builder
''' or '''\
Use the sphinx-build command to build the docs, like so:
sphinx-build -b builder %s %s
''' % (srcdir, builddir)) + '''\
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
''')
def generate(d, overwrite=True, silent=False):
'''Borrowed from Sphinx 1.3b3'''
"""Generate project based on values in *d*."""
texescape.init()
if 'mastertoctree' not in d:
d['mastertoctree'] = ''
if 'mastertocmaxdepth' not in d:
d['mastertocmaxdepth'] = 2
d['project_fn'] = make_filename(d['project'])
d['project_manpage'] = d['project_fn'].lower()
d['now'] = time.asctime()
d['project_underline'] = column_width(d['project']) * '='
d['copyright'] = time.strftime('%Y') + ', ' + d['author']
d['author_texescaped'] = text_type(d['author']
).translate(texescape.tex_escape_map)
d['project_doc'] = d['project'] + ' Documentation'
d['project_doc_texescaped'] = text_type(d['project'] + ' Documentation'
).translate(texescape.tex_escape_map)
# escape backslashes and single quotes in strings that are put into
# a Python string literal
for key in ('project', 'project_doc', 'project_doc_texescaped',
'author', 'author_texescaped', 'copyright',
'version', 'release', 'master'):
d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
if not path.isdir(d['path']):
mkdir_p(d['path'])
srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
mkdir_p(srcdir)
d['exclude_patterns'] = ''
#if d['sep']:
# builddir = path.join(d['path'], 'build')
#
#else:
# builddir = path.join(srcdir, d['dot'] + 'build')
# d['exclude_patterns'] = repr(d['dot'] + 'build')
#mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))
def write_file(fpath, content, newline=None):
if overwrite or not path.isfile(fpath):
print('Creating file %s.' % fpath)
f = open(fpath, 'wt', encoding='utf-8', newline=newline)
try:
f.write(content)
finally:
f.close()
else:
print('File %s already exists, skipping.' % fpath)
conf_text = ABLOG_CONF % d
write_file(path.join(srcdir, 'conf.py'), conf_text)
masterfile = path.join(srcdir, d['master'] + d['suffix'])
write_file(masterfile, ABLOG_INDEX % d)
about = path.join(srcdir, 'about' + d['suffix'])
write_file(about, ABLOG_ABOUT % d)
d['post_date'] = datetime.datetime.today().strftime('%b %d, %Y')
firstpost = path.join(srcdir, 'first-post' + d['suffix'])
write_file(firstpost, ABLOG_POST % d)
if silent:
return
print(bold('Finished: An initial directory structure has been created.'))