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_url": "https://example.org/",
"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_empty_nav(self):
conf = config.Config(schema=defaults.get_schema())
conf.load_dict({
'site_name':
'Example',
'config_file_path':
os.path.join(os.path.abspath('.'), 'mkdocs.yml')
})
conf.validate()
self.assertEqual(conf['nav'], None)
def test_missing_site_name(self):
c = config.Config(schema=defaults.get_schema())
c.load_dict({})
errors, warnings = c.validate()
self.assertEqual(len(errors), 1)
self.assertEqual(errors[0][0], 'site_name')
self.assertEqual(str(errors[0][1]),
'Required configuration not provided.')
self.assertEqual(len(warnings), 0)
def test_unrecognised_keys(self):
c = base.Config(schema=defaults.get_schema())
c.load_dict({'not_a_valid_config_option': "test"})
failed, warnings = c.validate()
self.assertIn(
('not_a_valid_config_option',
'Unrecognised configuration name: not_a_valid_config_option'),
warnings)
def test_copy_pages_to_nav(self):
# TODO: remove this when pages config setting is fully deprecated.
conf = config.Config(schema=defaults.get_schema())
conf.load_dict({
'site_name':
'Example',
'pages': ['index.md', 'about.md'],
'config_file_path':
os.path.join(os.path.abspath('.'), 'mkdocs.yml')
})
conf.validate()
self.assertEqual(conf['nav'], ['index.md', 'about.md'])
def test_site_url_and_use_directory_urls_undefined(self):
conf = config.Config(schema=defaults.get_schema())
conf.load_dict({
'site_name':
'Example',
'config_file_path':
os.path.join(os.path.abspath('.'), 'mkdocs.yml')
})
errors, warnings = conf.validate()
self.assertEqual(conf['site_url'], '')
self.assertFalse(conf['use_directory_urls'])
self.assertEqual(len(warnings), 2)
self.assertEqual(len(errors), 0)
def test_error_on_pages(self):
conf = config.Config(schema=defaults.get_schema())
conf.load_dict({
'site_name': 'Example',
'pages': ['index.md', 'about.md'],
})
errors, warnings = conf.validate()
self.assertEqual(warnings, [])
self.assertEqual(len(errors), 1)
self.assertEqual(
str(errors[0][1]),
"The configuration option 'pages' was removed from MkDocs. Use 'nav' instead."
)
def load_config(config_file=None, **kwargs):
"""
Load the configuration for a given file object or name
The config_file can either be a file object, string or None. If it is None
the default `mkdocs.yml` filename will loaded.
Extra kwargs are passed to the configuration to replace any default values
unless they themselves are None.
"""
options = kwargs.copy()
# Filter None values from the options. This usually happens with optional
# parameters from Click.
for key, value in options.copy().items():
if value is None:
options.pop(key)
with _open_config_file(config_file) as fd:
options['config_file_path'] = getattr(fd, 'name', '')
# Initialise the config with the default schema.
from mkdocs.config.defaults import get_schema
cfg = Config(schema=get_schema(),
config_file_path=options['config_file_path'])
# load the config file
cfg.load_file(fd)
# Then load the options to overwrite anything in the config.
cfg.load_dict(options)
errors, warnings = cfg.validate()
for config_name, warning in warnings:
log.warning(f"Config value: '{config_name}'. Warning: {warning}")
for config_name, error in errors:
log.error(f"Config value: '{config_name}'. Error: {error}")
for key, value in cfg.items():
log.debug(f"Config value: '{key}' = {value!r}")
if len(errors) > 0:
raise exceptions.Abort("Aborted with {} Configuration Errors!".format(
len(errors)))
elif cfg['strict'] and len(warnings) > 0:
raise exceptions.Abort(
"Aborted with {} Configuration Warnings in 'strict' mode!".format(
len(warnings)))
return cfg
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_defaults.get_schema(),
config_file_path=cfg['config_file_path'])
conf.load_dict(cfg)
errors_warnings = conf.validate()
assert (errors_warnings == ([], [])), errors_warnings
return conf