def test_theme(self):
mytheme = tempfile.mkdtemp()
custom = tempfile.mkdtemp()
configs = [
dict(), # default theme
{"theme": "readthedocs"}, # builtin theme
{"theme_dir": mytheme}, # custom only
{"theme": "cosmo", "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, 'cosmo'), search_asset_dir],
)
for config_contents, result in six.moves.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_theme_config_missing_name(self):
config = {
'custom_dir': 'custom',
}
option = config_options.Theme()
self.assertRaises(config_options.ValidationError, option.validate,
config)
def test_uninstalled_theme_as_config(self):
config = {
'name': 'mkdocs2'
}
option = config_options.Theme()
self.assertRaises(config_options.ValidationError,
option.validate, config)
def test_theme_name_is_none(self):
config = {
'name': None
}
option = config_options.Theme()
value = option.validate(config)
self.assertEqual(config, value)
def test_theme_as_simple_config(self):
config = {
'name': 'mkdocs'
}
option = config_options.Theme()
value = option.validate(config)
self.assertEqual(config, value)
def test_post_validation_none_theme_name_and_missing_custom_dir(self):
config = {
'theme': {
'name': None
}
}
option = config_options.Theme()
self.assertRaises(config_options.ValidationError,
option.post_validation, config, 'theme')
def test_post_validation_locale(self):
config = {
'theme': {
'name': 'mkdocs',
'locale': 'fr'
}
}
option = config_options.Theme()
option.post_validation(config, 'theme')
self.assertEqual('fr', config['theme']['locale'].language)
def test_post_validation_locale_invalid_type(self):
config = {
'theme': {
'name': 'mkdocs',
'locale': 0
}
}
option = config_options.Theme()
self.assertRaises(config_options.ValidationError,
option.post_validation, config, 'theme')
def test_post_validation_inexisting_custom_dir(self, abs_base_path):
config = {
'theme': {
'name': None,
'custom_dir': abs_base_path + '/inexisting_custom_dir',
}
}
option = config_options.Theme()
self.assertRaises(config_options.ValidationError,
option.post_validation, config, 'theme')
def test_post_validation_locale_none(self):
config = {
'theme': {
'name': 'mkdocs',
'locale': None
}
}
option = config_options.Theme()
with self.assertRaises(config_options.ValidationError):
option.post_validation(config, 'theme')
def test_theme_as_complex_config(self):
config = {
'name': 'mkdocs',
'custom_dir': 'custom',
'static_templates': ['sitemap.html'],
'show_sidebar': False
}
option = config_options.Theme()
value = option.validate(config)
self.assertEqual(config, value)
def test_theme(self):
option = config_options.Theme()
value = option.validate("mkdocs")
self.assertEqual("mkdocs", value)
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'])),
)
def test_theme_invalid_type(self):
config = ['mkdocs2']
option = config_options.Theme()
self.assertRaises(config_options.ValidationError, option.validate,
config)
def test_theme_invalid(self):
option = config_options.Theme()
self.assertRaises(config_options.ValidationError, option.validate,
"mkdocs2")
def test_theme_default(self):
option = config_options.Theme(default='mkdocs')
value = option.validate(None)
self.assertEqual({'name': 'mkdocs'}, value)
('pages', config_options.Nav()),
# The full URL to where the documentation will be hosted
('site_url', config_options.URL()),
# A description for the documentation project that will be added to the
# 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.
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'])
def test_theme_as_string(self):
option = config_options.Theme()
value = option.validate("mkdocs")
self.assertEqual({'name': 'mkdocs'}, value)
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_uninstalled_theme_as_string(self):
option = config_options.Theme()
self.assertRaises(config_options.ValidationError, option.validate,
"mkdocs2")