def test_simple_theme(self):
theme = Theme(name='mkdocs')
self.assertEqual(
theme.dirs,
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir])
self.assertEqual(theme.static_templates, {'404.html', 'sitemap.xml'})
self.assertEqual(
get_vars(theme), {
'locale': parse_locale('en'),
'include_search_page': False,
'search_index_only': False,
'analytics': {
'gtag': None
},
'highlightjs': True,
'hljs_style': 'github',
'hljs_languages': [],
'navigation_depth': 2,
'nav_style': 'primary',
'shortcuts': {
'help': 191,
'next': 78,
'previous': 80,
'search': 83
}
})
def test_custom_dir(self):
custom = tempfile.mkdtemp()
theme = Theme(name='mkdocs', custom_dir=custom)
self.assertEqual(
theme.dirs,
[custom,
os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir])
def on_config(self, config):
# Theme
config["theme"] = Theme(name="material")
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
search_plugin = SearchPlugin()
search_plugin.load_config({})
config["plugins"]["search"] = search_plugin
# Markdown Extensions
config["markdown_extensions"].append("admonition")
config["markdown_extensions"].append("abbr")
config["markdown_extensions"].append("attr_list")
config["markdown_extensions"].append("def_list")
config["markdown_extensions"].append("codehilite")
config["mdx_configs"]["codehilite"] = {
"linenums": True,
"guess_lang": False,
"pygments_style": "friendly",
}
config["markdown_extensions"].append("toc")
config["mdx_configs"]["toc"] = {
"permalink": True,
}
config["markdown_extensions"].append("footnotes")
config["markdown_extensions"].append("markdown.extensions.tables")
config["markdown_extensions"].append("pymdownx.betterem")
config["mdx_configs"]["pymdownx.betterem"] = {
"smart_enable": "all",
}
config["markdown_extensions"].append("pymdownx.caret")
config["markdown_extensions"].append("pymdownx.critic")
config["markdown_extensions"].append("pymdownx.details")
config["markdown_extensions"].append("pymdownx.emoji")
config["mdx_configs"]["pymdownx.emoji"] = {
"emoji_generator": "!!python/name:pymdownx.emoji.to_svg",
}
config["markdown_extensions"].append("pymdownx.inlinehilite")
config["markdown_extensions"].append("pymdownx.magiclink")
config["markdown_extensions"].append("pymdownx.mark")
config["markdown_extensions"].append("pymdownx.smartsymbols")
config["markdown_extensions"].append("pymdownx.superfences")
config["markdown_extensions"].append("pymdownx.tasklist")
config["mdx_configs"]["pymdownx.tasklist"] = {
"custom_checkbox": True,
}
config["markdown_extensions"].append("pymdownx.tilde")
return config
def test_custom_dir_only(self):
custom = tempfile.mkdtemp()
theme = Theme(name=None, custom_dir=custom)
self.assertEqual(
theme.dirs,
[custom, mkdocs_templates_dir]
)
def on_config(self, config):
# Theme
config["theme"] = Theme(name="material")
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
search_plugin = SearchPlugin()
search_plugin.load_config({})
config["plugins"]["search"] = search_plugin
# Markdown Extensions
config['markdown_extensions'].append('admonition')
config['markdown_extensions'].append('abbr')
config['markdown_extensions'].append('attr_list')
config['markdown_extensions'].append('def_list')
config['markdown_extensions'].append('codehilite')
config['mdx_configs']['codehilite'] = {
'linenums': True,
'guess_lang': False,
'pygments_style': 'friendly',
}
config['markdown_extensions'].append('toc')
config['mdx_configs']['toc'] = {
'permalink': True,
}
config['markdown_extensions'].append('footnotes')
config['markdown_extensions'].append('markdown.extensions.tables')
config['markdown_extensions'].append('pymdownx.betterem')
config['mdx_configs']['pymdownx.betterem'] = {
'smart_enable': 'all',
}
config['markdown_extensions'].append('pymdownx.caret')
config['markdown_extensions'].append('pymdownx.critic')
config['markdown_extensions'].append('pymdownx.details')
config['markdown_extensions'].append('pymdownx.emoji')
config['mdx_configs']['pymdownx.emoji'] = {
'emoji_generator': '!!python/name:pymdownx.emoji.to_svg',
}
config['markdown_extensions'].append('pymdownx.inlinehilite')
config['markdown_extensions'].append('pymdownx.magiclink')
config['markdown_extensions'].append('pymdownx.mark')
config['markdown_extensions'].append('pymdownx.smartsymbols')
config['markdown_extensions'].append('pymdownx.superfences')
config['markdown_extensions'].append('pymdownx.tasklist')
config['mdx_configs']['pymdownx.tasklist'] = {
'custom_checkbox': True,
}
config['markdown_extensions'].append('pymdownx.tilde')
return config
def test_simple_theme(self):
theme = Theme(name='mkdocs')
self.assertEqual(
theme.dirs,
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir]
)
self.assertEqual(theme.static_templates, set(['404.html', 'sitemap.xml']))
self.assertEqual(get_vars(theme), {})
def test_vars(self):
theme = Theme(name='mkdocs', foo='bar', baz=True)
self.assertEqual(theme['foo'], 'bar')
self.assertEqual(theme['baz'], True)
self.assertTrue('new' not in theme)
self.assertRaises(KeyError, lambda t, k: t[k], theme, 'new')
theme['new'] = 42
self.assertTrue('new' in theme)
self.assertEqual(theme['new'], 42)
def test_theme_overrides_dirs(self):
custom_theme_dir = "/tmp/my_custom_theme_dir"
self.mkdocs_yaml_config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
self.mkdocs_yaml_config["theme"].dirs.append(custom_theme_dir)
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
self.assertTrue(custom_theme_dir in final_config["theme"].dirs)
self.assertTrue(
self.techdocscore.tmp_dir_techdocs_theme.name in final_config["theme"].dirs
)
def test_theme_overrides_techdocs_metadata(self):
self.mkdocs_yaml_config["theme"] = Theme(
name=TECHDOCS_DEFAULT_THEME, static_templates=["my_static_temples"]
)
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
self.assertTrue("my_static_temples" in final_config["theme"].static_templates)
self.assertTrue(
"techdocs_metadata.json" in final_config["theme"].static_templates
)
def test_vars(self):
theme = Theme(name='mkdocs', foo='bar', baz=True)
self.assertEqual(theme['foo'], 'bar')
self.assertEqual(theme['baz'], True)
self.assertTrue('new' not in theme)
with self.assertRaises(KeyError):
theme['new']
theme['new'] = 42
self.assertTrue('new' in theme)
self.assertEqual(theme['new'], 42)
def test_simple_theme(self):
theme = Theme(name='mkdocs')
self.assertEqual(
theme.dirs,
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir])
self.assertEqual(theme.static_templates,
set(['404.html', 'sitemap.xml']))
self.assertEqual(get_vars(theme), {
'include_search_page': False,
'search_index_only': False
})
def on_config(self, config):
# Theme
config['theme'] = Theme(name="material")
# Plugins
del config['plugins']['techdocs-core']
search_plugin = SearchPlugin()
search_plugin.load_config({})
config['plugins']['search'] = search_plugin
return config
class MkDocsTemplateBridge(TemplateBridge):
"""A TemplateBridge that uses the mkdocs theme's Jinja2 environment for rendering.
"""
def init(self, builder, theme, dirs=None):
user_provided = builder.app.config.mkdocs_theme
# Check that the theme actually exists.
theme_entry_points = entry_points()["mkdocs.themes"]
available_themes = {ep.name: ep.value for ep in theme_entry_points}
if user_provided not in available_themes:
raise ExtensionError(
"Could not find mkdocs theme named: {}".format(user_provided))
self.mkdocs_theme = MkDocsTheme(user_provided)
self._environment = self.mkdocs_theme.get_env()
self._translator = ContextTranslator(builder.app, self.mkdocs_theme)
# TODO: add in configuration from mkdocs_theme into the
# RawConfigParser at theme.config
for key in self.mkdocs_theme:
value = self.mkdocs_theme[key]
theme.config.set("options", key, value)
@property
def translator(self):
assert hasattr(self, "_translator"), "WHAT."
return self._translator
@property
def environment(self):
assert hasattr(self, "_environment"), "WHAT."
return self._environment
def render(self, template, context):
try:
context, template = self._translator.translate(context, template)
return self._environment.get_template(template).render(context)
except Exception:
return ("Error occurred in MkDocsTemplateBridge.render()\n"
f"<pre>{html.escape(traceback.format_exc())}</pre>")
def render_string(self, source, context):
try:
context, _ = self._translator.translate(context,
template_name=None)
return self._environment.from_string(source).render(context)
except Exception:
return ("Error occurred in MkDocsTemplateBridge.render_string()\n"
f"<pre>{html.escape(traceback.format_exc())}</pre>")
def newest_template_mtime(self) -> float:
return max(mtimes_of_files(self.mkdocs_theme.dirs, ".html"))
def test_simple_theme(self):
theme = Theme(name='mkdocs')
self.assertEqual(
theme.dirs,
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir]
)
self.assertEqual(theme.static_templates, set(['404.html', 'sitemap.xml']))
self.assertEqual(get_vars(theme), {
'include_search_page': False,
'search_index_only': False,
'highlightjs': True,
'hljs_style': 'github',
'hljs_languages': [],
'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
})
def test_inherited_theme(self):
m = mock.Mock(side_effect=[{
'extends': 'readthedocs',
'static_templates': ['child.html']
}, {
'static_templates': ['parent.html']
}])
with mock.patch('mkdocs.utils.yaml_load', m) as m:
theme = Theme(name='mkdocs')
self.assertEqual(m.call_count, 2)
self.assertEqual(theme.dirs, [
os.path.join(theme_dir, 'mkdocs'),
os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir
])
self.assertEqual(theme.static_templates,
{'sitemap.xml', 'child.html', 'parent.html'})
def init(self, builder, theme, dirs=None):
user_provided = builder.app.config.mkdocs_theme
# Check that the theme actually exists.
theme_entry_points = entry_points()["mkdocs.themes"]
available_themes = {ep.name: ep.value for ep in theme_entry_points}
if user_provided not in available_themes:
raise ExtensionError(
"Could not find mkdocs theme named: {}".format(user_provided))
self.mkdocs_theme = MkDocsTheme(user_provided)
self._environment = self.mkdocs_theme.get_env()
self._translator = ContextTranslator(builder.app, self.mkdocs_theme)
# TODO: add in configuration from mkdocs_theme into the
# RawConfigParser at theme.config
for key in self.mkdocs_theme:
value = self.mkdocs_theme[key]
theme.config.set("options", key, value)
def on_config(self, config):
# Theme
config["theme"] = Theme(name="material")
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
search_plugin = SearchPlugin()
search_plugin.load_config({})
config["plugins"]["search"] = search_plugin
return config
def on_config(self, config):
with open(
os.path.join(self.tmp_dir_techdocs_theme.name,
"techdocs_metadata.json"),
"w+",
) as fp:
fp.write(
'{{ {"site_name": (config.site_name | string), '
'"site_description": (config.site_description | string)} | tojson }}'
)
mdx_configs_override = {}
if "mdx_configs" in config:
mdx_configs_override = config["mdx_configs"].copy()
# Theme
if config["theme"].name != TECHDOCS_DEFAULT_THEME:
config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
elif config["theme"].name == TECHDOCS_DEFAULT_THEME:
log.info(
"[mkdocs-techdocs-core] Overridden '%s' theme settings in use",
TECHDOCS_DEFAULT_THEME,
)
config["theme"].static_templates.update({"techdocs_metadata.json"})
config["theme"].dirs.append(self.tmp_dir_techdocs_theme.name)
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
# Markdown Extensions
if "markdown_extensions" not in config:
config["markdown_extensions"] = []
if "mdx_configs" not in config:
config["mdx_configs"] = {}
config["markdown_extensions"].append("admonition")
config["markdown_extensions"].append("toc")
config["mdx_configs"]["toc"] = {
"permalink": True,
}
config["markdown_extensions"].append("pymdownx.caret")
config["markdown_extensions"].append("pymdownx.critic")
config["markdown_extensions"].append("pymdownx.details")
config["markdown_extensions"].append("pymdownx.emoji")
config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg}
config["markdown_extensions"].append("pymdownx.inlinehilite")
config["markdown_extensions"].append("pymdownx.magiclink")
config["markdown_extensions"].append("pymdownx.mark")
config["markdown_extensions"].append("pymdownx.smartsymbols")
config["markdown_extensions"].append("pymdownx.superfences")
config["markdown_extensions"].append("pymdownx.highlight")
config["mdx_configs"]["pymdownx.highlight"] = {
"linenums": True,
"pygments_lang_class": True,
}
config["markdown_extensions"].append("pymdownx.extra")
config["mdx_configs"]["pymdownx.betterem"] = {
"smart_enable": "all",
}
config["markdown_extensions"].append("pymdownx.tabbed")
config["mdx_configs"]["pymdownx.tabbed"] = {
"alternate_style": True,
}
config["markdown_extensions"].append("pymdownx.tasklist")
config["mdx_configs"]["pymdownx.tasklist"] = {
"custom_checkbox": True,
}
config["markdown_extensions"].append("pymdownx.tilde")
config["markdown_extensions"].append("markdown_inline_graphviz")
config["markdown_extensions"].append("plantuml_markdown")
config["markdown_extensions"].append("mdx_truly_sane_lists")
# merge config supplied by user in the mkdocs.yml
for key in mdx_configs_override:
if key in config["mdx_configs"]:
default_config = config["mdx_configs"][key]
override_config = mdx_configs_override[key]
default_config.update(override_config)
return config
def test_theme_overrides_removed_when_name_is_not_material(self):
## we want to force the theme mkdocs to this test
self.mkdocs_yaml_config["theme"] = Theme(name="mkdocs")
self.mkdocs_yaml_config["theme"]["features"] = ["navigation.sections"]
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
self.assertFalse("navigation.sections" in final_config["theme"]["features"])
def test_theme_overrides_when_name_is_material(self):
self.mkdocs_yaml_config["theme"] = Theme(name=TECHDOCS_DEFAULT_THEME)
self.mkdocs_yaml_config["theme"]["features"] = ["navigation.sections"]
final_config = self.techdocscore.on_config(self.mkdocs_yaml_config)
self.assertTrue("navigation.sections" in final_config["theme"]["features"])
def test_no_theme_config(self, m):
theme = Theme(name='mkdocs')
self.assertEqual(m.call_count, 1)
self.assertEqual(theme.static_templates, {'sitemap.xml'})
def get_default_theme():
return Theme(name="mkdocs")
def static_templates(self):
theme = Theme(name='mkdocs', static_templates='foo.html')
self.assertEqual(theme.static_templates,
{'404.html', 'sitemap.xml', 'foo.html'})
def on_config(self, config):
with open(
os.path.join(self.tmp_dir_techdocs_theme.name, "techdocs_metadata.json"),
"w+",
) as fp:
fp.write(
'{\n "site_name": "{{ config.site_name }}",\n "site_description": "{{ config.site_description }}"\n}'
)
mdx_configs_override = {}
if "mdx_configs" in config:
mdx_configs_override = config["mdx_configs"].copy()
# Theme
config["theme"] = Theme(
name="material",
static_templates=[
"techdocs_metadata.json",
],
)
config["theme"].dirs.append(self.tmp_dir_techdocs_theme.name)
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
# Markdown Extensions
if "markdown_extensions" not in config:
config["markdown_extensions"] = []
if "mdx_configs" not in config:
config["mdx_configs"] = {}
config["markdown_extensions"].append("admonition")
config["markdown_extensions"].append("toc")
config["mdx_configs"]["toc"] = {
"permalink": True,
}
config["markdown_extensions"].append("pymdownx.caret")
config["markdown_extensions"].append("pymdownx.critic")
config["markdown_extensions"].append("pymdownx.details")
config["markdown_extensions"].append("pymdownx.emoji")
config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg}
config["markdown_extensions"].append("pymdownx.inlinehilite")
config["markdown_extensions"].append("pymdownx.magiclink")
config["markdown_extensions"].append("pymdownx.mark")
config["markdown_extensions"].append("pymdownx.smartsymbols")
config["markdown_extensions"].append("pymdownx.superfences")
config["mdx_configs"]["pymdownx.superfences"] = {
"legacy_tab_classes": True,
}
config["markdown_extensions"].append("pymdownx.highlight")
config["mdx_configs"]["pymdownx.highlight"] = {
"linenums": True,
}
config["markdown_extensions"].append("pymdownx.extra")
config["mdx_configs"]["pymdownx.betterem"] = {
"smart_enable": "all",
}
config["markdown_extensions"].append("pymdownx.tabbed")
config["markdown_extensions"].append("pymdownx.tasklist")
config["mdx_configs"]["pymdownx.tasklist"] = {
"custom_checkbox": True,
}
config["markdown_extensions"].append("pymdownx.tilde")
config["markdown_extensions"].append("markdown_inline_graphviz")
config["markdown_extensions"].append("plantuml_markdown")
# merge config supplied by user in the mkdocs.yml
for key in mdx_configs_override:
if key in config["mdx_configs"]:
default_config = config["mdx_configs"][key]
override_config = mdx_configs_override[key]
default_config.update(override_config)
return config
def on_config(self, config):
fp = open(
os.path.join(tempfile.gettempdir(), "techdocs_metadata.json"),
"w+")
fp.write(
'{\n "site_name": "{{ config.site_name }}",\n "site_description": "{{ config.site_description }}"\n}'
)
# Theme
config["theme"] = Theme(
name="material",
static_templates=[
"techdocs_metadata.json",
],
)
config["theme"].dirs.append(tempfile.gettempdir())
# Plugins
del config["plugins"]["techdocs-core"]
search_plugin = SearchPlugin()
search_plugin.load_config({})
monorepo_plugin = MonorepoPlugin()
monorepo_plugin.load_config({})
config["plugins"]["search"] = search_plugin
config["plugins"]["monorepo"] = monorepo_plugin
search_plugin = SearchPlugin()
search_plugin.load_config({})
config["plugins"]["search"] = search_plugin
# Markdown Extensions
config["markdown_extensions"].append("admonition")
config["markdown_extensions"].append("abbr")
config["markdown_extensions"].append("attr_list")
config["markdown_extensions"].append("def_list")
config["markdown_extensions"].append("codehilite")
config["mdx_configs"]["codehilite"] = {
"linenums": True,
"guess_lang": False,
"pygments_style": "friendly",
}
config["markdown_extensions"].append("toc")
config["mdx_configs"]["toc"] = {
"permalink": True,
}
config["markdown_extensions"].append("footnotes")
config["markdown_extensions"].append("markdown.extensions.tables")
config["markdown_extensions"].append("pymdownx.betterem")
config["mdx_configs"]["pymdownx.betterem"] = {
"smart_enable": "all",
}
config["markdown_extensions"].append("pymdownx.caret")
config["markdown_extensions"].append("pymdownx.critic")
config["markdown_extensions"].append("pymdownx.details")
config["markdown_extensions"].append("pymdownx.emoji")
config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg}
config["markdown_extensions"].append("pymdownx.inlinehilite")
config["markdown_extensions"].append("pymdownx.magiclink")
config["markdown_extensions"].append("pymdownx.mark")
config["markdown_extensions"].append("pymdownx.smartsymbols")
config["markdown_extensions"].append("pymdownx.superfences")
config["markdown_extensions"].append("pymdownx.tasklist")
config["mdx_configs"]["pymdownx.tasklist"] = {
"custom_checkbox": True,
}
config["markdown_extensions"].append("pymdownx.tilde")
config["markdown_extensions"].append("markdown_inline_graphviz")
config["markdown_extensions"].append("plantuml_markdown")
return config
