def add_versions_menu_js_file(app):
"""Add doctr-versions-menu.js file as a static js file to Sphinx."""
tmpdir = tempfile.mkdtemp()
app.config._doctr_versions_menu_temp_dir = tmpdir
js_file_name = 'doctr-versions-menu.js'
renderer = SphinxRenderer(app.config.templates_path +
[str(Path(__file__).parent / '_template')])
context = dict(
json_file=_JS(
'"/" + window.location.pathname.split("/")[1] + "/versions.json"'),
github_project_url=_JS('getGithubProjectUrl()'),
current_folder=_JS('getGhPagesCurrentFolder()'),
badge_only=(app.config.html_theme != 'sphinx_rtd_theme'),
)
context.update(app.config.doctr_versions_menu_conf)
with (Path(tmpdir) / js_file_name).open('w') as js_file:
js_file.write(
renderer.render(template_name='doctr-versions-menu.js_t',
context=context))
app.config.html_static_path.append(tmpdir)
app.add_js_file(js_file_name)
if context['badge_only']:
app.config.html_static_path.extend([
str(Path(__file__).parent / '_css'),
str(Path(__file__).parent / '_fonts'),
])
app.add_css_file('badge_only.css')
def render(self, name: str, context: Dict) -> str:
template = SphinxRenderer(template_dir)
return template.render(name, context)
def render(self, name: str, context: Dict) -> str:
template = SphinxRenderer(template_dir)
return template.render(name, context)
def render(self, name, context):
# type: (str, Dict) -> str
template = SphinxRenderer(template_dir)
return template.render(name, context)
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*."""
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*."""
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.
''')