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")