def test_default(self):
with directory() as tmp:
# given
tmp.dir('documentary')
tmp.store(['src'], '')
tmp.store(['documentary', 'src'], '')
# when
doc, root, template, output = resolve_paths(
args(root=tmp(), template='src'))
# then
self.assertEqual(
tmp('documentary'),
doc,
msg='Failed to assert that documentary path is returned')
self.assertEqual(
tmp(),
root,
msg=
'Failed to assert that root path is current working directory')
self.assertEqual(
'src',
template,
msg=
'Failed to assert template is joined with current working directory'
)
self.assertEqual(
root,
output,
msg="Failed to assert that output path is root path")
def test_should_return_default_for_missing_fragment(self):
with directory() as tmp:
# when
result = fragment(tmp.join('folder'), 'missing', default=lambda: 'returned')
# then
self.assertEqual('returned', result)
def test_many(self):
with stubbed_output() as lines:
with directory() as tmp:
# when
document_many(documentary_path=resource('input/documentary'),
root_path=resource('input'),
templates_path='src',
output_path=tmp.join('output'))
# then
with open(resource('expected/preg.php'), 'r') as expected:
self.assertEqual(expected.read(),
tmp.open('output/src/SafeRegex/preg.php'))
with open(resource('expected/Pattern.php'), 'r') as expected:
self.assertEqual(
expected.read(),
tmp.open('output/src/CleanRegex/Pattern.php'))
self.assertPathsMatch(
actual=lines(),
expected=[
f'File "{resource("input")}/src/SafeRegex/preg.php" documented',
f'File "{resource("input")}/src/CleanRegex/Pattern.php" documented',
])
def test_should_traverse_fallback(self):
with directory() as tmp:
# given
tmp.store('folder/first.html', 'Foo')
# when
result = fragment_fallback(tmp.join('folder'), 'first', 'second', tmp.join())
# then
self.assertEqual(result, "Foo")
def test_should_discover_itself(self):
with directory() as tmp:
# given
tmp.store('src/app/first.py', 'template')
# when
result = discover_templates('src/app/first.py', tmp.join(), tmp.join('documentary'))
# then
self.assertEqual(['src/app/first.py'], result)
def test_should_raise_for_no_documentary(self):
with directory() as tmp:
# given
tmp.store('src/file', 'template')
# when
with self.assertRaises(TemplatesDiscoveryException) as error:
discover_templates('src', tmp.join(), tmp.join('documentary'))
# then
self.assertEqual("File/folder 'src' is not documented", str(error.exception))
def test_missing_files(self):
with directory() as tmp:
# when
details, _ = load_details(
declaration=tmp.join('missing.json'),
decorations=tmp.join('missing.json'),
definitions=tmp.join('missing.json'),
)
# then
self.assertEqual({}, details)
def test_should_raise_for_missing_file(self):
with directory() as tmp:
# given
tmp.store('src/app/first.py', 'template')
# when
with self.assertRaises(FileNotFoundError) as error:
discover_templates('src/app/second.py', tmp.join(), tmp.join('documentary'))
# then
self.assertEqual(str(error.exception), "File/folder 'src/app/second.py' does not exist")
def test_should_traverse_fallback_project(self):
with directory() as tmp:
# given
tmp.store('project/fragment/second.html', 'Global')
tmp.store('a/b/c/foo.html', '')
# when
result = fragment_fallback(tmp.join('a', 'b', 'c'), 'first', 'second', tmp.join())
# then
self.assertEqual(result, "Global")
def test_raise_for_missing_documentary(self):
with directory() as tmp:
# given
with self.assertRaises(Exception) as error:
# when
resolve_paths(args(root=tmp(), template='src'))
# then
self.assertEqual(
tmp.strip(str(error.exception)),
'To generate documentation, navigate to a directory with "documentary" folder'
)
def test_should_raise_for_not_documented_folder(self):
with directory() as tmp:
# given
tmp.store('src/main/second.py', 'template file')
tmp.dir('docs/src/test')
# when
with self.assertRaises(TemplatesDiscoveryException) as error:
discover_templates('src/main', tmp.join(), documentary=tmp.join('docs'))
# then
self.assertEqual("File/folder 'src/main' is not documented", str(error.exception))
def test_raise_for_missing_template(self):
with directory() as tmp:
# given
tmp.dir('documentary')
# when
with self.assertRaises(Exception) as error:
# when
resolve_paths(args(root=tmp(), template='src'))
# then
self.assertEqual(
r"""Tried to documentation file "src", but it doesn't exist""",
tmp.strip((str(error.exception))))
def test_raise_for_missing_documentation(self):
with directory() as tmp:
# given
tmp.dir('documentary')
tmp.store(['src'], '')
# when
with self.assertRaises(Exception) as error:
# when
resolve_paths(args(root=tmp(), template='src'))
# then
self.assertEqual(
'Directory "src" is missing in documentary folder',
str(error.exception))
def test_empty_files(self):
with directory() as tmp:
# given
tmp.store('declaration.json', dumps({}))
tmp.store('decorations.json', dumps({}))
tmp.store('definitions.json', dumps({}))
# when
details, _ = load_details(
declaration=tmp.join('declaration.json'),
decorations=tmp.join('decorations.json'),
definitions=tmp.join('definitions.json'),
)
# then
self.assertEqual(second=details, first={})
def test_single(self):
with stubbed_output() as lines:
with directory() as tmp:
# when
document(
documentary_path=resource('input/documentary'),
documentation_path=resource(
'input/documentary/src/SafeRegex/preg.php'),
template_path=resource('input/src/SafeRegex/preg.php'),
output_path=tmp.join('preg.php'))
# then
with open(resource('expected/preg.php'), 'r') as expected:
self.assertEqual(expected.read(), tmp.open('preg.php'))
self.assertEqual([
f'File "{resource("input/src/SafeRegex/preg.php")}" documented'
], lines())
def test_should_discover_children(self):
with directory() as tmp:
# given - templates
tmp.store('src/main/second.py', 'template file')
tmp.store('src/main/sub/first.py', 'template file')
tmp.store('src/test/first.py', 'template file')
# given - documents
tmp.store('docs/src/main/first.py/definition.json', '{}')
tmp.store('docs/src/main/second.py/definition.json', '{}')
tmp.store('docs/src/main/sub/first.py/definition.json', '{}')
tmp.store('docs/src/main/sub/second.py/definition.json', '{}')
tmp.store('docs/src/test/first.py/definition.json', '{}')
tmp.store('docs/src/test/second.py/definition.json', '{}')
# when
result = discover_templates('src', tmp.join(), documentary=tmp.join('docs'))
# then
self.assertPathsMatch(actual=result, expected=[
'src/main/second.py',
'src/main/sub/first.py',
'src/test/first.py',
])
def test_should_raise_for_missing_fragment(self):
with directory() as tmp:
# then
self.assertRaises(MissingFragmentException, lambda: fragment(tmp.join('folder'), 'missing'))