def load_config(**cfg):
""" Helper to build a simple config for testing. """
path_base = os.path.join(
os.path.abspath(os.path.dirname(__file__)), 'integration', 'minimal'
)
cfg = cfg or {}
if 'site_name' not in cfg:
cfg['site_name'] = 'Example'
if 'config_file_path' not in cfg:
cfg['config_file_path'] = os.path.join(path_base, 'mkdocs.yml')
if 'docs_dir' not in cfg:
# Point to an actual dir to avoid a 'does not exist' error on validation.
cfg['docs_dir'] = os.path.join(path_base, 'docs')
conf = config.Config(schema=config.DEFAULT_SCHEMA, config_file_path=cfg['config_file_path'])
conf.load_dict(cfg)
errors_warnings = conf.validate()
assert(errors_warnings == ([], [])), errors_warnings
return conf
def test_theme(self):
mytheme = tempfile.mkdtemp()
custom = tempfile.mkdtemp()
configs = [
dict(), # default theme
{
"theme": "readthedocs"
}, # builtin theme
{
"theme_dir": mytheme
}, # custom only
{
"theme": "readthedocs",
"theme_dir": custom
}, # builtin and custom
]
abs_path = os.path.abspath(os.path.dirname(__file__))
mkdocs_dir = os.path.abspath(os.path.join(abs_path, '..', '..'))
theme_dir = os.path.abspath(os.path.join(mkdocs_dir, 'themes'))
search_asset_dir = os.path.abspath(
os.path.join(mkdocs_dir, 'assets', 'search'))
results = (
[os.path.join(theme_dir, 'mkdocs'), search_asset_dir],
[os.path.join(theme_dir, 'readthedocs'), search_asset_dir],
[mytheme, search_asset_dir],
[custom,
os.path.join(theme_dir, 'readthedocs'), search_asset_dir],
)
for config_contents, result in zip(configs, results):
c = config.Config(schema=(
('theme', config_options.Theme(default='mkdocs')),
('theme_dir', config_options.ThemeDir(exists=True)),
))
c.load_dict(config_contents)
c.validate()
self.assertEqual(c['theme_dir'], result)
def test_default_pages_nested(self):
tmp_dir = tempfile.mkdtemp()
try:
open(os.path.join(tmp_dir, 'index.md'), 'w').close()
open(os.path.join(tmp_dir, 'getting-started.md'), 'w').close()
open(os.path.join(tmp_dir, 'about.md'), 'w').close()
os.makedirs(os.path.join(tmp_dir, 'subA'))
open(os.path.join(tmp_dir, 'subA', 'index.md'), 'w').close()
os.makedirs(os.path.join(tmp_dir, 'subA', 'subA1'))
open(os.path.join(tmp_dir, 'subA', 'subA1', 'index.md'),
'w').close()
os.makedirs(os.path.join(tmp_dir, 'subC'))
open(os.path.join(tmp_dir, 'subC', 'index.md'), 'w').close()
os.makedirs(os.path.join(tmp_dir, 'subB'))
open(os.path.join(tmp_dir, 'subB', 'index.md'), 'w').close()
conf = config.Config(schema=config.DEFAULT_SCHEMA)
conf.load_dict({
'site_name':
'Example',
'docs_dir':
tmp_dir,
'config_file_path':
os.path.join(os.path.abspath('.'), 'mkdocs.yml')
})
conf.validate()
self.assertEqual([
'index.md', 'about.md', 'getting-started.md', {
'subA': [
os.path.join('subA', 'index.md'), {
'subA1':
[os.path.join('subA', 'subA1', 'index.md')]
}
]
}, {
'subB': [os.path.join('subB', 'index.md')]
}, {
'subC': [os.path.join('subC', 'index.md')]
}
], conf['pages'])
finally:
shutil.rmtree(tmp_dir)
def ext_markdown(**kwargs):
"""Yield a Markdown instance with MkdocstringsExtension, with config adjustments from **kwargs.
Arguments:
**kwargs: Changes to apply to the config, on top of the default config.
Yields:
A `markdown.Markdown` instance.
"""
conf = config.Config(schema=config.DEFAULT_SCHEMA)
conf_dict = {
"site_name": "foo",
"plugins": [{
"mkdocstrings": {
"default_handler": "python"
}
}],
**kwargs,
}
# Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289
mdx_configs = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))
conf.load_dict(conf_dict)
assert conf.validate() == ([], [])
conf["mdx_configs"] = mdx_configs
conf["markdown_extensions"].insert(
0, "toc") # Guaranteed to be added by MkDocs.
conf = conf["plugins"]["mkdocstrings"].on_config(conf)
conf = conf["plugins"]["autorefs"].on_config(conf)
md = Markdown(extensions=conf["markdown_extensions"],
extension_configs=conf["mdx_configs"])
yield md
conf["plugins"]["mkdocstrings"].on_post_build(conf)
def fixture_ext_markdown(request, tmp_path):
"""Yield a Markdown instance with MkdocstringsExtension, with config adjustments."""
conf = config.Config(schema=get_schema())
conf_dict = {
"site_name": "foo",
"site_dir": str(tmp_path),
"plugins": [{"mkdocstrings": {"default_handler": "python"}}],
**getattr(request, "param", {}),
}
# Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289
mdx_configs = dict(ChainMap(*conf_dict.get("markdown_extensions", [])))
conf.load_dict(conf_dict)
assert conf.validate() == ([], [])
conf["mdx_configs"] = mdx_configs
conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs.
conf = conf["plugins"]["mkdocstrings"].on_config(conf)
conf = conf["plugins"]["autorefs"].on_config(conf)
md = Markdown(extensions=conf["markdown_extensions"], extension_configs=conf["mdx_configs"])
yield md
conf["plugins"]["mkdocstrings"].on_post_build(conf)
def test_theme(self):
with TemporaryDirectory() as mytheme, TemporaryDirectory() as custom:
configs = [
dict(), # default theme
{
"theme": "readthedocs"
}, # builtin theme
{
"theme": {
'name': 'readthedocs'
}
}, # builtin as complex
{
"theme": {
'name': None,
'custom_dir': mytheme
}
}, # custom only as complex
{
"theme": {
'name': 'readthedocs',
'custom_dir': custom
}
}, # builtin and custom as complex
{ # user defined variables
'theme': {
'name': 'mkdocs',
'locale': 'fr',
'static_templates': ['foo.html'],
'show_sidebar': False,
'some_var': 'bar'
}
}
]
mkdocs_dir = os.path.abspath(os.path.dirname(mkdocs.__file__))
mkdocs_templates_dir = os.path.join(mkdocs_dir, 'templates')
theme_dir = os.path.abspath(os.path.join(mkdocs_dir, 'themes'))
results = ({
'dirs':
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'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
}
}
}, {
'dirs':
[os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'locale': parse_locale('en'),
'include_search_page': True,
'search_index_only': False,
'analytics': {
'gtag': None
},
'highlightjs': True,
'hljs_languages': [],
'include_homepage_in_sidebar': True,
'prev_next_buttons_location': 'bottom',
'navigation_depth': 4,
'sticky_navigation': True,
'titles_only': False,
'collapse_navigation': True
}
}, {
'dirs':
[os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'locale': parse_locale('en'),
'include_search_page': True,
'search_index_only': False,
'analytics': {
'gtag': None
},
'highlightjs': True,
'hljs_languages': [],
'include_homepage_in_sidebar': True,
'prev_next_buttons_location': 'bottom',
'navigation_depth': 4,
'sticky_navigation': True,
'titles_only': False,
'collapse_navigation': True
}
}, {
'dirs': [mytheme, mkdocs_templates_dir],
'static_templates': ['sitemap.xml'],
'vars': {
'locale': parse_locale('en')
}
}, {
'dirs': [
custom,
os.path.join(theme_dir, 'readthedocs'),
mkdocs_templates_dir
],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'locale': parse_locale('en'),
'include_search_page': True,
'search_index_only': False,
'analytics': {
'gtag': None
},
'highlightjs': True,
'hljs_languages': [],
'include_homepage_in_sidebar': True,
'prev_next_buttons_location': 'bottom',
'navigation_depth': 4,
'sticky_navigation': True,
'titles_only': False,
'collapse_navigation': True
}
}, {
'dirs':
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml', 'foo.html'],
'vars': {
'locale': parse_locale('fr'),
'show_sidebar': False,
'some_var': 'bar',
'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
}
}
})
for config_contents, result in zip(configs, results):
c = config.Config(schema=(('theme',
config_options.Theme(
default='mkdocs')), ))
c.load_dict(config_contents)
errors, warnings = c.validate()
self.assertEqual(len(errors), 0)
self.assertEqual(c['theme'].dirs, result['dirs'])
self.assertEqual(c['theme'].static_templates,
set(result['static_templates']))
self.assertEqual({k: c['theme'][k]
for k in iter(c['theme'])}, result['vars'])
def test_theme(self):
with TemporaryDirectory() as mytheme, TemporaryDirectory() as custom:
configs = [
dict(), # default theme
{
"theme": "readthedocs"
}, # builtin theme
{
"theme_dir": mytheme
}, # custom only
{
"theme": "readthedocs",
"theme_dir": custom
}, # builtin and custom
{
"theme": {
'name': 'readthedocs'
}
}, # builtin as complex
{
"theme": {
'name': None,
'custom_dir': mytheme
}
}, # custom only as complex
{
"theme": {
'name': 'readthedocs',
'custom_dir': custom
}
}, # builtin and custom as complex
{ # user defined variables
'theme': {
'name': 'mkdocs',
'static_templates': ['foo.html'],
'show_sidebar': False,
'some_var': 'bar'
}
}
]
mkdocs_dir = os.path.abspath(os.path.dirname(mkdocs.__file__))
mkdocs_templates_dir = os.path.join(mkdocs_dir, 'templates')
theme_dir = os.path.abspath(os.path.join(mkdocs_dir, 'themes'))
results = ({
'dirs':
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'include_search_page': False,
'search_index_only': False
}
}, {
'dirs':
[os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'include_search_page': True,
'search_index_only': False
}
}, {
'dirs': [mytheme, mkdocs_templates_dir],
'static_templates': ['sitemap.xml'],
'vars': {}
}, {
'dirs': [
custom,
os.path.join(theme_dir, 'readthedocs'),
mkdocs_templates_dir
],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'include_search_page': True,
'search_index_only': False
}
}, {
'dirs':
[os.path.join(theme_dir, 'readthedocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'include_search_page': True,
'search_index_only': False
}
}, {
'dirs': [mytheme, mkdocs_templates_dir],
'static_templates': ['sitemap.xml'],
'vars': {}
}, {
'dirs': [
custom,
os.path.join(theme_dir, 'readthedocs'),
mkdocs_templates_dir
],
'static_templates': ['404.html', 'sitemap.xml'],
'vars': {
'include_search_page': True,
'search_index_only': False
}
}, {
'dirs':
[os.path.join(theme_dir, 'mkdocs'), mkdocs_templates_dir],
'static_templates': ['404.html', 'sitemap.xml', 'foo.html'],
'vars': {
'show_sidebar': False,
'some_var': 'bar',
'include_search_page': False,
'search_index_only': False
}
})
for config_contents, result in zip(configs, results):
c = config.Config(schema=(
('theme', config_options.Theme(default='mkdocs')),
('theme_dir', config_options.ThemeDir(exists=True)),
))
c.load_dict(config_contents)
errors, warnings = c.validate()
self.assertEqual(len(errors), 0)
self.assertEqual(c['theme'].dirs, result['dirs'])
self.assertEqual(c['theme'].static_templates,
set(result['static_templates']))
self.assertEqual(
dict([(k, c['theme'][k]) for k in iter(c['theme'])]),
result['vars'])
