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'])