def test_doc_dir_in_site_dir(self):
j = os.path.join
option = config_options.SiteDir()
docs_dir = config_options.Dir()
# The parent dir is not the same on every system, so use the actual dir name
parent_dir = mkdocs.__file__.split(os.sep)[-3]
test_configs = (
{'docs_dir': j('site', 'docs'), 'site_dir': 'site'},
{'docs_dir': 'docs', 'site_dir': '.'},
{'docs_dir': '.', 'site_dir': '.'},
{'docs_dir': 'docs', 'site_dir': ''},
{'docs_dir': '', 'site_dir': ''},
{'docs_dir': j('..', parent_dir, 'docs'), 'site_dir': 'docs'},
)
for test_config in test_configs:
test_config['config_file_path'] = j(os.path.abspath('..'), 'mkdocs.yml')
test_config['docs_dir'] = docs_dir.validate(test_config['docs_dir'])
test_config['site_dir'] = option.validate(test_config['site_dir'])
self.assertRaises(config_options.ValidationError,
option.post_validation, test_config, 'site_dir')
def test_site_dir_in_docs_dir(self):
j = os.path.join
test_configs = (
{
'docs_dir': 'docs',
'site_dir': j('docs', 'site')
},
{
'docs_dir': '.',
'site_dir': 'site'
},
{
'docs_dir': '',
'site_dir': 'site'
},
)
for test_config in test_configs:
docs_dir = config_options.Dir()
option = config_options.SiteDir()
test_config['docs_dir'] = docs_dir.validate(
test_config['docs_dir'])
test_config['site_dir'] = option.validate(test_config['site_dir'])
option.post_validation(test_config, 'key')
self.assertEqual(len(option.warnings), 1)
self.assertEqual(
option.warnings[0][:50],
"The 'site_dir' should not be within the 'docs_dir'")
def test_doc_dir_in_site_dir(self):
j = os.path.join
test_configs = (
{'docs_dir': j('site', 'docs'), 'site_dir': 'site'},
{'docs_dir': 'docs', 'site_dir': '.'},
{'docs_dir': '.', 'site_dir': '.'},
{'docs_dir': 'docs', 'site_dir': ''},
{'docs_dir': '', 'site_dir': ''},
{'docs_dir': j('..', 'mkdocs', 'docs'), 'site_dir': 'docs'},
)
conf = {
'config_file_path': j(os.path.abspath('..'), 'mkdocs.yml')
}
for test_config in test_configs:
patch = conf.copy()
patch.update(test_config)
# Same as the default schema, but don't verify the docs_dir exists.
c = config.Config(schema=(
('docs_dir', config_options.Dir(default='docs')),
('site_dir', config_options.SiteDir(default='site')),
('config_file_path', config_options.Type(utils.string_types))
))
c.load_dict(patch)
errors, warnings = c.validate()
self.assertEqual(len(errors), 1)
self.assertEqual(warnings, [])
def test_doc_dir_in_site_dir(self):
j = os.path.join
test_configs = (
{'docs_dir': 'docs', 'site_dir': j('docs', 'site')},
{'docs_dir': j('site', 'docs'), 'site_dir': 'site'},
{'docs_dir': 'docs', 'site_dir': '.'},
{'docs_dir': '.', 'site_dir': 'site'},
{'docs_dir': '.', 'site_dir': '.'},
{'docs_dir': 'docs', 'site_dir': ''},
{'docs_dir': '', 'site_dir': 'site'},
{'docs_dir': '', 'site_dir': ''},
{'docs_dir': j('..', 'mkdocs', 'docs'), 'site_dir': 'docs'},
)
conf = {
'site_name': 'Example',
}
for test_config in test_configs:
patch = conf.copy()
patch.update(test_config)
# Same as the default schema, but don't verify the docs_dir exists.
c = config.Config(schema=(
('docs_dir', config_options.Dir(default='docs')),
('site_dir', config_options.SiteDir(default='site')),
))
c.load_dict(patch)
self.assertRaises(config_options.ValidationError, c.validate)
def validate_config(self, config):
""" Given a config with values for site_dir and doc_dir, run site_dir post_validation. """
site_dir = config_options.SiteDir()
docs_dir = config_options.Dir()
config['config_file_path'] = os.path.join(os.path.abspath('..'), 'mkdocs.yml')
config['docs_dir'] = docs_dir.validate(config['docs_dir'])
config['site_dir'] = site_dir.validate(config['site_dir'])
site_dir.post_validation(config, 'site_dir')
return True # No errors were raised
def test_doc_dir_in_site_dir(self):
j = os.path.join
option = config_options.SiteDir()
docs_dir = config_options.Dir()
test_configs = (
{
'docs_dir': 'docs',
'site_dir': j('docs', 'site')
},
{
'docs_dir': j('site', 'docs'),
'site_dir': 'site'
},
{
'docs_dir': 'docs',
'site_dir': '.'
},
{
'docs_dir': '.',
'site_dir': 'site'
},
{
'docs_dir': '.',
'site_dir': '.'
},
{
'docs_dir': 'docs',
'site_dir': ''
},
{
'docs_dir': '',
'site_dir': 'site'
},
{
'docs_dir': '',
'site_dir': ''
},
{
'docs_dir': j('..', 'mkdocs', 'docs'),
'site_dir': 'docs'
},
)
for test_config in test_configs:
test_config['docs_dir'] = docs_dir.validate(
test_config['docs_dir'])
test_config['site_dir'] = option.validate(test_config['site_dir'])
self.assertRaises(config_options.ValidationError,
option.post_validation, test_config, 'key')
def test_site_dir_in_docs_dir(self):
j = os.path.join
test_configs = (
{'docs_dir': 'docs', 'site_dir': j('docs', 'site')},
{'docs_dir': '.', 'site_dir': 'site'},
{'docs_dir': '', 'site_dir': 'site'},
)
for test_config in test_configs:
test_config['config_file_path'] = j(os.path.abspath('..'), 'mkdocs.yml')
docs_dir = config_options.Dir()
option = config_options.SiteDir()
test_config['docs_dir'] = docs_dir.validate(test_config['docs_dir'])
test_config['site_dir'] = option.validate(test_config['site_dir'])
self.assertRaises(config_options.ValidationError,
option.post_validation, test_config, 'site_dir')
def validate_config(self, config):
""" Given a config with values for site_dir and doc_dir, run site_dir post_validation. """
site_dir = config_options.SiteDir()
docs_dir = config_options.Dir()
fname = os.path.join(os.path.abspath('..'), 'mkdocs.yml')
config['docs_dir'] = docs_dir.validate(config['docs_dir'])
config['site_dir'] = site_dir.validate(config['site_dir'])
schema = [
('site_dir', site_dir),
('docs_dir', docs_dir),
]
cfg = Config(schema, fname)
cfg.load_dict(config)
failed, warned = cfg.validate()
if failed:
raise config_options.ValidationError(failed)
return True
# HTML meta tags.
# The name of the keywords to add to the HTML meta tags
('site_keywords', config_options.Type(str)),
# The name of the keywords to add to the HTML meta tags
('site_description', config_options.Type(str)),
# The name of the author to add to the HTML meta tags
('site_author', config_options.Type(str)),
# The MkDocs theme for the documentation.
('theme', config_options.Theme(default='mkdocs')),
# The directory containing the documentation markdown.
('docs_dir', config_options.Dir(default='docs', exists=True)),
# The directory where the site will be built to
('site_dir', config_options.SiteDir(default='site')),
# A copyright notice to add to the footer of documentation.
('copyright', config_options.Type(str)),
# set of values for Google analytics containing the account IO and domain,
# this should look like, ['UA-27795084-5', 'mkdocs.org']
('google_analytics', config_options.Type(list, length=2)),
# The address on which to serve the live reloading docs server.
('dev_addr', config_options.IpAddress(default='127.0.0.1:8000')),
# If `True`, use `<page_name>/index.hmtl` style files with hyperlinks to
# the directory.If `False`, use `<page_name>.html style file with
# hyperlinks to the file.
# True generates nicer URLs, but False is useful if browsing the output on
def get_schema():
return (
# Reserved for internal use, stores the mkdocs.yml config file.
('config_file_path', config_options.Type(str)),
# The title to use for the documentation
('site_name', config_options.Type(str, required=True)),
# Defines the structure of the navigation.
('nav', config_options.Nav()),
# TODO: remove this when the `pages` config setting is fully deprecated.
('pages', config_options.Nav()),
# The full URL to where the documentation will be hosted
('site_url', config_options.URL(is_dir=True)),
# A description for the documentation project that will be added to the
# HTML meta tags.
('site_description', config_options.Type(str)),
# The name of the author to add to the HTML meta tags
('site_author', config_options.Type(str)),
# The MkDocs theme for the documentation.
('theme', config_options.Theme(default='mkdocs')),
# The directory containing the documentation markdown.
('docs_dir', config_options.Dir(default='docs', exists=True)),
# The directory where the site will be built to
('site_dir', config_options.SiteDir(default='site')),
# A copyright notice to add to the footer of documentation.
('copyright', config_options.Type(str)),
# set of values for Google analytics containing the account IO and domain,
# this should look like, ['UA-27795084-5', 'mkdocs.org']
('google_analytics', config_options.Type(list, length=2)),
# The address on which to serve the live reloading docs server.
('dev_addr', config_options.IpAddress(default='127.0.0.1:8000')),
# If `True`, use `<page_name>/index.hmtl` style files with hyperlinks to
# the directory.If `False`, use `<page_name>.html style file with
# hyperlinks to the file.
# True generates nicer URLs, but False is useful if browsing the output on
# a filesystem.
('use_directory_urls', config_options.Type(bool, default=True)),
# Specify a link to the project source repo to be included
# in the documentation pages.
('repo_url', config_options.RepoURL()),
# A name to use for the link to the project source repo.
# Default, If repo_url is unset then None, otherwise
# "GitHub", "Bitbucket" or "GitLab" for known url or Hostname
# for unknown urls.
('repo_name', config_options.Type(str)),
# Specify a URI to the docs dir in the project source repo, relative to the
# repo_url. When set, a link directly to the page in the source repo will
# be added to the generated HTML. If repo_url is not set also, this option
# is ignored.
('edit_uri', config_options.Type(str)),
# Specify which css or javascript files from the docs directory should be
# additionally included in the site.
('extra_css', config_options.Type(list, default=[])),
('extra_javascript', config_options.Type(list, default=[])),
# Similar to the above, but each template (HTML or XML) will be build with
# Jinja2 and the global context.
('extra_templates', config_options.Type(list, default=[])),
# PyMarkdown extension names.
('markdown_extensions', config_options.MarkdownExtensions(
builtins=['toc', 'tables', 'fenced_code'],
configkey='mdx_configs', default=[])),
# PyMarkdown Extension Configs. For internal use only.
('mdx_configs', config_options.Private()),
# enabling strict mode causes MkDocs to stop the build when a problem is
# encountered rather than display an error.
('strict', config_options.Type(bool, default=False)),
# the remote branch to commit to when using gh-deploy
('remote_branch', config_options.Type(
str, default='gh-pages')),
# the remote name to push to when using gh-deploy
('remote_name', config_options.Type(str, default='origin')),
# extra is a mapping/dictionary of data that is passed to the template.
# This allows template authors to require extra configuration that not
# relevant to all themes and doesn't need to be explicitly supported by
# MkDocs itself. A good example here would be including the current
# project version.
('extra', config_options.SubConfig()),
# a list of plugins. Each item may contain a string name or a key value pair.
# A key value pair should be the string name (as the key) and a dict of config
# options (as the value).
('plugins', config_options.Plugins(default=['search'])),
)
