def test_file_eq(self):
file = File('a.md',
'/path/to/docs',
'/path/to/site',
use_directory_urls=False)
self.assertTrue(file == File(
'a.md', '/path/to/docs', '/path/to/site',
use_directory_urls=False))
def test_create_media_urls_use_directory_urls(self):
expected_results = {
'https://media.cdn.org/jq.js': [
'https://media.cdn.org/jq.js', 'https://media.cdn.org/jq.js',
'https://media.cdn.org/jq.js'
],
'http://media.cdn.org/jquery.js': [
'http://media.cdn.org/jquery.js',
'http://media.cdn.org/jquery.js',
'http://media.cdn.org/jquery.js'
],
'//media.cdn.org/jquery.js': [
'//media.cdn.org/jquery.js', '//media.cdn.org/jquery.js',
'//media.cdn.org/jquery.js'
],
'media.cdn.org/jquery.js': [
'media.cdn.org/jquery.js', '../media.cdn.org/jquery.js',
'../../media.cdn.org/jquery.js'
],
'local/file/jquery.js': [
'local/file/jquery.js', '../local/file/jquery.js',
'../../local/file/jquery.js'
],
'local\\windows\\file\\jquery.js': [
'local/windows/file/jquery.js',
'../local/windows/file/jquery.js',
'../../local/windows/file/jquery.js'
],
'image.png': ['image.png', '../image.png', '../../image.png'],
'style.css?v=20180308c': [
'style.css?v=20180308c', '../style.css?v=20180308c',
'../../style.css?v=20180308c'
],
'#some_id': ['#some_id', '#some_id', '#some_id']
}
cfg = load_config(use_directory_urls=True)
pages = [
Page(
'Home',
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']), cfg),
Page(
'About',
File('about.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']), cfg),
Page(
'FooBar',
File('foo/bar.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']), cfg)
]
for i, page in enumerate(pages):
urls = utils.create_media_urls(expected_results.keys(), page)
self.assertEqual([v[i] for v in expected_results.values()], urls)
def test_context_base_url_nested_page_use_directory_urls(self):
nav_cfg = [{'Home': 'index.md'}, {'Nested': 'foo/bar.md'}]
cfg = load_config(nav=nav_cfg)
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
File('foo/bar.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
])
nav = get_navigation(files, cfg)
context = build.get_context(nav, files, cfg, nav.pages[1])
self.assertEqual(context['base_url'], '../..')
def test_context_extra_css_js_from_nested_page_use_directory_urls(self):
nav_cfg = [{'Home': 'index.md'}, {'Nested': 'foo/bar.md'}]
cfg = load_config(nav=nav_cfg,
extra_css=['style.css'],
extra_javascript=['script.js'])
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
File('foo/bar.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
])
nav = get_navigation(files, cfg)
context = build.get_context(nav, files, cfg, nav.pages[1])
self.assertEqual(context['extra_css'], ['../../style.css'])
self.assertEqual(context['extra_javascript'], ['../../script.js'])
def test_nav_from_files(self):
expected = dedent("""
Page(title=[blank], url='/')
Page(title=[blank], url='/about/')
""")
cfg = load_config(site_url='http://example.com/')
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('about.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])
])
site_navigation = get_navigation(files, cfg)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 2)
self.assertEqual(len(site_navigation.pages), 2)
self.assertEqual(repr(site_navigation.homepage), "Page(title=[blank], url='/')")
def test_nav_bad_links(self):
nav_cfg = [
{'Home': 'index.md'},
{'Missing': 'missing.html'},
{'Bad External': 'example.com'}
]
expected = dedent("""
Page(title='Home', url='/')
Link(title='Missing', url='missing.html')
Link(title='Bad External', url='example.com')
""")
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
with self.assertLogs('elstir', level='WARNING') as cm:
site_navigation = get_navigation(files, cfg)
self.assertEqual(
cm.output,
[
"WARNING:elstir.structure.nav:A relative path to 'missing.html' is included "
"in the 'nav' configuration, which is not found in the documentation files",
"WARNING:elstir.structure.nav:A relative path to 'example.com' is included "
"in the 'nav' configuration, which is not found in the documentation files"
]
)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 3)
self.assertEqual(len(site_navigation.pages), 1)
def test_build_extra_template(self):
cfg = load_config()
files = Files([
File('foo.html', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
build._build_extra_template('foo.html', files, cfg, mock.Mock())
def test_nav_external_links(self):
nav_cfg = [
{'Home': 'index.md'},
{'Local': '/local.html'},
{'External': 'http://example.com/external.html'}
]
expected = dedent("""
Page(title='Home', url='/')
Link(title='Local', url='/local.html')
Link(title='External', url='http://example.com/external.html')
""")
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
with self.assertLogs('elstir', level='DEBUG') as cm:
site_navigation = get_navigation(files, cfg)
self.assertEqual(
cm.output,
[
"DEBUG:elstir.structure.nav:An absolute path to '/local.html' is included in the "
"'nav' configuration, which presumably points to an external resource.",
"DEBUG:elstir.structure.nav:An external link to 'http://example.com/external.html' "
"is included in the 'nav' configuration."
]
)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 3)
self.assertEqual(len(site_navigation.pages), 1)
def test_populate_page(self, docs_dir):
cfg = load_config(docs_dir=docs_dir)
file = File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
page = Page('Foo', file, cfg)
build._populate_page(page, cfg, Files([file]))
self.assertEqual(page.content, '<p>page content</p>')
def test_copy_file_dirty_not_modified(self, src_dir, dest_dir):
file = File('test.txt', src_dir, dest_dir, use_directory_urls=False)
file.is_modified = mock.Mock(return_value=False)
dest_path = os.path.join(dest_dir, 'test.txt')
file.copy_file(dirty=True)
self.assertPathIsFile(dest_path)
with open(dest_path, 'r', encoding='utf-8') as f:
self.assertEqual(f.read(), 'destination content')
def test_file_ne(self):
file = File('a.md',
'/path/to/docs',
'/path/to/site',
use_directory_urls=False)
# Different filename
self.assertTrue(file != File(
'b.md', '/path/to/docs', '/path/to/site', use_directory_urls=False)
)
# Different src_path
self.assertTrue(file != File('a.md',
'/path/to/other',
'/path/to/site',
use_directory_urls=False))
# Different URL
self.assertTrue(file != File(
'a.md', '/path/to/docs', '/path/to/site', use_directory_urls=True))
def test_nav_from_nested_files(self):
expected = dedent("""
Page(title=[blank], url='/')
Section(title='About')
Page(title=[blank], url='/about/license/')
Page(title=[blank], url='/about/release-notes/')
Section(title='Api guide')
Page(title=[blank], url='/api-guide/debugging/')
Page(title=[blank], url='/api-guide/running/')
Page(title=[blank], url='/api-guide/testing/')
Section(title='Advanced')
Page(title=[blank], url='/api-guide/advanced/part-1/')
""")
cfg = load_config(site_url='http://example.com/')
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('about/license.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('about/release-notes.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/debugging.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/running.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/testing.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/advanced/part-1.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
])
site_navigation = get_navigation(files, cfg)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 3)
self.assertEqual(len(site_navigation.pages), 7)
self.assertEqual(repr(site_navigation.homepage), "Page(title=[blank], url='/')")
def test_populate_page_dirty_not_modified(self, site_dir, docs_dir):
cfg = load_config(docs_dir=docs_dir, site_dir=site_dir)
file = File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
page = Page('Foo', file, cfg)
build._populate_page(page, cfg, Files([file]), dirty=True)
# Content is empty as file read was skipped
self.assertEqual(page.markdown, None)
self.assertEqual(page.content, None)
def test_nav_missing_page(self):
nav_cfg = [
{'Home': 'index.md'}
]
expected = dedent("""
Page(title='Home', url='/')
""")
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('page_not_in_nav.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])
])
site_navigation = get_navigation(files, cfg)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 1)
self.assertEqual(len(site_navigation.pages), 1)
for file in files:
self.assertIsInstance(file.page, Page)
def test_nav_no_title(self):
nav_cfg = [
'index.md',
{'About': 'about.md'}
]
expected = dedent("""
Page(title=[blank], url='/')
Page(title='About', url='/about/')
""")
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([
File(nav_cfg[0], cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File(nav_cfg[1]['About'], cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])
])
site_navigation = get_navigation(files, cfg)
self.assertEqual(str(site_navigation).strip(), expected)
self.assertEqual(len(site_navigation.items), 2)
self.assertEqual(len(site_navigation.pages), 2)
def test_populate_page_dirty_modified(self, site_dir):
cfg = load_config(site_dir=site_dir)
file = File('testing.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
page = Page('Foo', file, cfg)
build._populate_page(page, cfg, Files([file]), dirty=True)
self.assertTrue(page.markdown.startswith('# Welcome to elstir'))
self.assertTrue(
page.content.startswith(
'<h1 id="welcome-to-elstir">Welcome to elstir</h1>'))
def test_context_base_url_homepage(self):
nav_cfg = [{'Home': 'index.md'}]
cfg = load_config(nav=nav_cfg, use_directory_urls=False)
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
nav = get_navigation(files, cfg)
context = build.get_context(nav, files, cfg, nav.pages[0])
self.assertEqual(context['base_url'], '.')
def test_skip_ioerror_extra_template(self, mock_open):
cfg = load_config()
files = Files([
File('foo.html', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
with self.assertLogs('elstir', level='INFO') as cm:
build._build_extra_template('foo.html', files, cfg, mock.Mock())
self.assertEqual(cm.output, [
"WARNING:elstir.commands.build:Error reading template 'foo.html': Error message."
])
def test_file_name_with_space(self):
f = File('foo bar.md',
'/path/to/docs',
'/path/to/site',
use_directory_urls=False)
self.assertPathsEqual(f.src_path, 'foo bar.md')
self.assertPathsEqual(f.abs_src_path, '/path/to/docs/foo bar.md')
self.assertPathsEqual(f.dest_path, 'foo bar.html')
self.assertPathsEqual(f.abs_dest_path, '/path/to/site/foo bar.html')
self.assertEqual(f.url, 'foo%20bar.html')
self.assertEqual(f.name, 'foo bar')
def build_page(title, path, config, md_src=''):
""" Helper which returns a Page object. """
files = Files([
File(path, config['docs_dir'], config['site_dir'],
config['use_directory_urls'])
])
page = Page(title, list(files)[0], config)
# Fake page.read_source()
page.markdown, page.meta = meta.get_data(md_src)
return page, files
def test_skip_extra_template_empty_output(self):
cfg = load_config()
files = Files([
File('foo.html', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
with self.assertLogs('elstir', level='INFO') as cm:
build._build_extra_template('foo.html', files, cfg, mock.Mock())
self.assertEqual(cm.output, [
"INFO:elstir.commands.build:Template skipped: 'foo.html' generated empty output."
])
def test_populate_page_read_plugin_error(self, docs_dir, mock_open):
cfg = load_config(docs_dir=docs_dir)
file = File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
page = Page('Foo', file, cfg)
with self.assertLogs('mkdocs', level='ERROR') as cm:
self.assertRaises(PluginError, build._populate_page, page, cfg,
Files([file]))
self.assertEqual(
cm.output,
["ERROR:mkdocs.commands.build:Error reading page 'index.md':"])
self.assert_mock_called_once(mock_open)
def test_skip_missing_extra_template(self):
cfg = load_config()
files = Files([
File('foo.html', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
with self.assertLogs('elstir', level='INFO') as cm:
build._build_extra_template('missing.html', files, cfg,
mock.Mock())
self.assertEqual(cm.output, [
"WARNING:elstir.commands.build:Template skipped: 'missing.html' not found in docs_dir."
])
def test_populate_page_read_error(self, docs_dir, mock_open):
cfg = load_config(docs_dir=docs_dir)
file = File('missing.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
page = Page('Foo', file, cfg)
with self.assertLogs('elstir', level='ERROR') as cm:
self.assertRaises(OSError, build._populate_page, page, cfg,
Files([file]))
self.assertEqual(cm.output, [
'ERROR:elstir.structure.pages:File not found: missing.md',
"ERROR:elstir.commands.build:Error reading page 'missing.md': Error message."
])
self.assert_mock_called_once(mock_open)
def test_build_page(self, site_dir):
cfg = load_config(site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls'])
])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, cfg['theme'].get_env())
self.assertPathIsFile(site_dir, 'index.html')
def test_get_by_type_nested_sections(self):
nav_cfg = [
{'Section 1': [
{'Section 2': [
{'Page': 'page.md'}
]}
]}
]
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([
File('page.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])
])
site_navigation = get_navigation(files, cfg)
self.assertEqual(len(_get_by_type(site_navigation, Section)), 2)
def test_context_extra_css_js_from_homepage(self):
nav_cfg = [{'Home': 'index.md'}]
cfg = load_config(nav=nav_cfg,
extra_css=['style.css'],
extra_javascript=['script.js'],
use_directory_urls=False)
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'],
cfg['use_directory_urls']),
])
nav = get_navigation(files, cfg)
context = build.get_context(nav, files, cfg, nav.pages[0])
self.assertEqual(context['extra_css'], ['style.css'])
self.assertEqual(context['extra_javascript'], ['script.js'])
def on_files(self, files, config):
# Scan the list of files to extract tags from meta
for f in files:
if not f.src_path.endswith(".md"):
continue
self.metadata.append(get_metadata(f.src_path, config["docs_dir"]))
# Create new file with tags
self.generate_tags_file()
# New file to add to the build
newfile = File(path=str(self.tags_filename),
src_dir=str(self.tags_folder),
dest_dir=config["site_dir"],
use_directory_urls=False)
files.append(newfile)
def test_md_file_nested(self):
f = File('foo/bar.md',
'/path/to/docs',
'/path/to/site',
use_directory_urls=False)
self.assertPathsEqual(f.src_path, 'foo/bar.md')
self.assertPathsEqual(f.abs_src_path, '/path/to/docs/foo/bar.md')
self.assertPathsEqual(f.dest_path, 'foo/bar.html')
self.assertPathsEqual(f.abs_dest_path, '/path/to/site/foo/bar.html')
self.assertEqual(f.url, 'foo/bar.html')
self.assertEqual(f.name, 'bar')
self.assertTrue(f.is_documentation_page())
self.assertFalse(f.is_static_page())
self.assertFalse(f.is_media_file())
self.assertFalse(f.is_javascript())
self.assertFalse(f.is_css())
def test_active(self):
nav_cfg = [
{'Home': 'index.md'},
{'API Guide': [
{'Running': 'api-guide/running.md'},
{'Testing': 'api-guide/testing.md'},
{'Debugging': 'api-guide/debugging.md'},
{'Advanced': [
{'Part 1': 'api-guide/advanced/part-1.md'},
]},
]},
{'About': [
{'Release notes': 'about/release-notes.md'},
{'License': 'about/license.md'}
]}
]
cfg = load_config(nav=nav_cfg, site_url='http://example.com/')
files = Files([
File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/running.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/testing.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/debugging.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('api-guide/advanced/part-1.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('about/release-notes.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
File('about/license.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls']),
])
site_navigation = get_navigation(files, cfg)
# Confirm nothing is active
self.assertTrue(all(page.active is False for page in site_navigation.pages))
self.assertTrue(all(item.active is False for item in site_navigation.items))
# Activate
site_navigation.items[1].children[3].children[0].active = True
# Confirm ancestors are activated
self.assertTrue(site_navigation.items[1].children[3].children[0].active)
self.assertTrue(site_navigation.items[1].children[3].active)
self.assertTrue(site_navigation.items[1].active)
# Confirm non-ancestors are not activated
self.assertFalse(site_navigation.items[0].active)
self.assertFalse(site_navigation.items[1].children[0].active)
self.assertFalse(site_navigation.items[1].children[1].active)
self.assertFalse(site_navigation.items[1].children[2].active)
self.assertFalse(site_navigation.items[2].active)
self.assertFalse(site_navigation.items[2].children[0].active)
self.assertFalse(site_navigation.items[2].children[1].active)
# Deactivate
site_navigation.items[1].children[3].children[0].active = False
# Confirm ancestors are deactivated
self.assertFalse(site_navigation.items[1].children[3].children[0].active)
self.assertFalse(site_navigation.items[1].children[3].active)
self.assertFalse(site_navigation.items[1].active)