def test_all_errors(tmpdir, local_docs, urls):
"""Test good root ref with all bad non-root refs.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
"""
pytest.run(local_docs, ['git', 'checkout', '-b', 'a_broken', 'master'])
local_docs.join('conf.py').write('master_doc = exception\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Broken version.'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'b_broken', 'a_broken'])
pytest.run(local_docs, ['git', 'push', 'origin', 'a_broken', 'b_broken'])
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['b_broken']['sha'], str(exported_root.join(versions['b_broken']['sha'])))
# Run.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
assert [r['name'] for r in versions.remotes] == ['master']
# Verify root HTML links.
urls(destination.join('contents.html'), ['<li><a href="master/contents.html">master</a></li>'])
urls(destination.join('master', 'contents.html'), ['<li><a href="contents.html">master</a></li>'])
def test_all_errors(tmpdir, local_docs, urls):
"""Test good root ref with all bad non-root refs.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
"""
pytest.run(local_docs, ['git', 'checkout', '-b', 'a_broken', 'master'])
local_docs.join('conf.py').write('master_doc = exception\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Broken version.'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'b_broken', 'a_broken'])
pytest.run(local_docs, ['git', 'push', 'origin', 'a_broken', 'b_broken'])
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['b_broken']['sha'],
str(exported_root.join(versions['b_broken']['sha'])))
# Run.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
assert [r['name'] for r in versions.remotes] == ['master']
# Verify root HTML links.
urls(destination.join('contents.html'),
['<li><a href="master/contents.html">master</a></li>'])
urls(destination.join('master', 'contents.html'),
['<li><a href="contents.html">master</a></li>'])
def test_single(tmpdir, local_docs, urls):
"""With single version.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
"""
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
# Run and verify directory.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
actual = sorted(f.relto(destination) for f in destination.visit() if f.check(dir=True))
expected = [
'.doctrees',
'_sources',
'_static',
'master',
join('master', '.doctrees'),
join('master', '_sources'),
join('master', '_static'),
]
assert actual == expected
# Verify HTML links.
urls(destination.join('contents.html'), ['<li><a href="master/contents.html">master</a></li>'])
urls(destination.join('master', 'contents.html'), ['<li><a href="contents.html">master</a></li>'])
def test_new_branch_tags(tmpdir, local_light, fail):
"""Test with new branches and tags unknown to local repo.
:param tmpdir: pytest fixture.
:param local_light: conftest fixture.
:param bool fail: Fail by not fetching.
"""
remotes = [r for r in list_remote(str(local_light)) if r[1] == 'ob_at']
# Fail.
sha = remotes[0][0]
target = tmpdir.ensure_dir('exported', sha)
if fail:
with pytest.raises(CalledProcessError):
export(str(local_light), sha, str(target))
return
# Fetch.
fetch_commits(str(local_light), remotes)
# Export.
export(str(local_light), sha, str(target))
files = [f.relto(target) for f in target.listdir()]
assert files == ['README']
assert target.join('README').read() == 'new'
def test_banner_branch(tmpdir, banner, config, local_docs, show_banner):
"""Test banner messages without tags.
:param tmpdir: pytest fixture.
:param banner: conftest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param bool show_banner: Show the banner.
"""
pytest.run(local_docs, ['git', 'checkout', '-b', 'old_build', 'master'])
pytest.run(local_docs, ['git', 'checkout', 'master'])
pytest.run(local_docs, ['git', 'rm', 'two.rst'])
local_docs.join('contents.rst').write(
'Test\n'
'====\n'
'\n'
'Sample documentation.\n'
'\n'
'.. toctree::\n'
' one\n'
)
pytest.run(local_docs, ['git', 'commit', '-am', 'Deleted.'])
pytest.run(local_docs, ['git', 'push', 'origin', 'master', 'old_build'])
config.show_banner = show_banner
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
versions['master']['found_docs'] = ('contents', 'one')
versions['old_build']['found_docs'] = ('contents', 'one', 'two')
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['old_build']['sha'], str(exported_root.join(versions['old_build']['sha'])))
# Run and verify files.
dst = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(dst), versions)
actual = sorted(f.relto(dst) for f in dst.visit(lambda p: p.basename in ('contents.html', 'one.html', 'two.html')))
expected = [
'contents.html', join('master', 'contents.html'), join('master', 'one.html'),
join('old_build', 'contents.html'), join('old_build', 'one.html'), join('old_build', 'two.html'), 'one.html'
]
assert actual == expected
# Verify no banner.
if not show_banner:
for path in expected:
banner(dst.join(path), None)
return
for path in ('contents.html', 'master/contents.html', 'master/one.html', 'one.html'):
banner(dst.join(path), None)
# Verify banner.
banner(dst.join('old_build', 'contents.html'), '../master/contents.html',
'the development version of Python. The main version is master')
banner(dst.join('old_build', 'one.html'), '../master/one.html',
'the development version of Python. The main version is master')
banner(dst.join('old_build', 'two.html'), '', 'the development version of Python')
def pre_build(local_root, versions):
"""Build docs for all versions to determine root directory and master_doc names.
Need to build docs to (a) avoid filename collision with files from root_ref and branch/tag names and (b) determine
master_doc config values for all versions (in case master_doc changes from e.g. contents.rst to index.rst between
versions).
Exports all commits into a temporary directory and returns the path to avoid re-exporting during the final build.
:param str local_root: Local path to git root directory.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
:return: Tempdir path with exported commits as subdirectories.
:rtype: str
"""
log = logging.getLogger(__name__)
exported_root = TempDir(True).name
# Extract all.
for sha in {r['sha'] for r in versions.remotes}:
target = os.path.join(exported_root, sha)
log.debug('Exporting %s to temporary directory.', sha)
export(local_root, sha, target)
# Build root.
remote = versions[Config.from_context().root_ref]
with TempDir() as temp_dir:
log.debug('Building root (before setting root_dirs) in temporary directory: %s', temp_dir)
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
build(source, temp_dir, versions, remote['name'], True)
existing = os.listdir(temp_dir)
# Define root_dir for all versions to avoid file name collisions.
for remote in versions.remotes:
root_dir = RE_INVALID_FILENAME.sub('_', remote['name'])
while root_dir in existing:
root_dir += '_'
remote['root_dir'] = root_dir
log.debug('%s root directory is %s', remote['name'], root_dir)
existing.append(root_dir)
# Get found_docs and master_doc values for all versions.
for remote in list(versions.remotes):
log.debug('Partially running sphinx-build to read configuration for: %s', remote['name'])
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
try:
config = read_config(source, remote['name'])
except HandledError:
log.warning('Skipping. Will not be building: %s', remote['name'])
versions.remotes.pop(versions.remotes.index(remote))
continue
remote['found_docs'] = config['found_docs']
remote['master_doc'] = config['master_doc']
return exported_root
def test_timezones(tmpdir, local):
"""Test mtime on RST files with different git commit timezones.
:param tmpdir: pytest fixture.
:param local: conftest fixture.
"""
files_dates = [
('local.rst', ''),
('UTC.rst', ' +0000'),
('PDT.rst', ' -0700'),
('PST.rst', ' -0800'),
]
# Commit files.
for name, offset in files_dates:
local.ensure(name)
pytest.run(local, ['git', 'add', name])
env = pytest.author_committer_dates(0)
env['GIT_AUTHOR_DATE'] += offset
env['GIT_COMMITTER_DATE'] += offset
pytest.run(local, ['git', 'commit', '-m', 'Added ' + name],
environ=env)
# Run.
target = tmpdir.ensure_dir('target')
sha = pytest.run(local, ['git', 'rev-parse', 'HEAD']).strip()
export(str(local), sha, str(target))
# Validate.
actual = {
i[0]: str(datetime.fromtimestamp(target.join(i[0]).mtime()))
for i in files_dates
}
if -time.timezone == -28800:
expected = {
'local.rst': '2016-12-05 03:17:05',
'UTC.rst': '2016-12-04 19:17:05',
'PDT.rst': '2016-12-05 02:17:05',
'PST.rst': '2016-12-05 03:17:05',
}
elif -time.timezone == 0:
expected = {
'local.rst': '2016-12-05 03:17:05',
'UTC.rst': '2016-12-05 03:17:05',
'PDT.rst': '2016-12-05 10:17:05',
'PST.rst': '2016-12-05 11:17:05',
}
else:
return pytest.skip(
'Need to add expected for {} timezone.'.format(-time.timezone))
assert actual == expected
def test_simple(tmpdir, local):
"""Test with just the README in one commit.
:param tmpdir: pytest fixture.
:param local: conftest fixture.
"""
target = tmpdir.ensure_dir('target')
sha = pytest.run(local, ['git', 'rev-parse', 'HEAD']).strip()
export(str(local), sha, str(target))
pytest.run(local, ['git', 'diff-index', '--quiet', 'HEAD', '--'
]) # Exit 0 if nothing changed.
files = [f.relto(target) for f in target.listdir()]
assert files == ['README']
def test_last_updated(tmpdir, local_docs):
"""Test last updated timestamp derived from git authored time.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
"""
local_docs.join('conf.py').write('html_last_updated_fmt = "%c"\n'
'html_theme="sphinx_rtd_theme"\n')
local_docs.join('two.rst').write('Changed\n', mode='a')
pytest.run(local_docs, ['git', 'commit', '-am', 'Changed two.'],
environ=pytest.author_committer_dates(10))
pytest.run(local_docs, ['git', 'checkout', '-b', 'other', 'master'])
local_docs.join('three.rst').write('Changed\n', mode='a')
pytest.run(local_docs, ['git', 'commit', '-am', 'Changed three.'],
environ=pytest.author_committer_dates(11))
pytest.run(local_docs, ['git', 'push', 'origin', 'master', 'other'])
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['other']['sha'],
str(exported_root.join(versions['other']['sha'])))
# Run.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
# Verify master.
one = RE_LAST_UPDATED.findall(
destination.join('master', 'one.html').read())
two = RE_LAST_UPDATED.findall(
destination.join('master', 'two.html').read())
three = RE_LAST_UPDATED.findall(
destination.join('master', 'three.html').read())
assert one == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
assert two == ['Last updated on Dec 5, 2016, 3:27:05 AM.\n']
assert three == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
# Verify other.
one = RE_LAST_UPDATED.findall(destination.join('other', 'one.html').read())
two = RE_LAST_UPDATED.findall(destination.join('other', 'two.html').read())
three = RE_LAST_UPDATED.findall(
destination.join('other', 'three.html').read())
assert one == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
assert two == ['Last updated on Dec 5, 2016, 3:27:05 AM.\n']
assert three == ['Last updated on Dec 5, 2016, 3:28:05 AM.\n']
def test_last_updated(tmpdir, local_docs):
"""Test last updated timestamp derived from git authored time.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
"""
local_docs.join('conf.py').write(
'html_last_updated_fmt = "%c"\n'
'html_theme="sphinx_rtd_theme"\n'
)
local_docs.join('two.rst').write('Changed\n', mode='a')
pytest.run(local_docs, ['git', 'commit', '-am', 'Changed two.'], environ=pytest.author_committer_dates(10))
pytest.run(local_docs, ['git', 'checkout', '-b', 'other', 'master'])
local_docs.join('three.rst').write('Changed\n', mode='a')
pytest.run(local_docs, ['git', 'commit', '-am', 'Changed three.'], environ=pytest.author_committer_dates(11))
pytest.run(local_docs, ['git', 'push', 'origin', 'master', 'other'])
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['other']['sha'], str(exported_root.join(versions['other']['sha'])))
# Run.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
# Verify master.
one = RE_LAST_UPDATED.findall(destination.join('master', 'one.html').read())
two = RE_LAST_UPDATED.findall(destination.join('master', 'two.html').read())
three = RE_LAST_UPDATED.findall(destination.join('master', 'three.html').read())
assert one == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
assert two == ['Last updated on Dec 5, 2016, 3:27:05 AM.\n']
assert three == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
# Verify other.
one = RE_LAST_UPDATED.findall(destination.join('other', 'one.html').read())
two = RE_LAST_UPDATED.findall(destination.join('other', 'two.html').read())
three = RE_LAST_UPDATED.findall(destination.join('other', 'three.html').read())
assert one == ['Last updated on Dec 5, 2016, 3:20:05 AM.\n']
assert two == ['Last updated on Dec 5, 2016, 3:27:05 AM.\n']
assert three == ['Last updated on Dec 5, 2016, 3:28:05 AM.\n']
def test_overwrite(tmpdir, local):
"""Test overwriting existing files.
:param tmpdir: pytest fixture.
:param local: conftest fixture.
"""
local.ensure('docs', '_templates', 'layout.html').write('three')
local.join('docs', 'conf.py').write('one')
local.join('docs', 'index.rst').write('two')
pytest.run(local, ['git', 'add', 'docs'])
pytest.run(local, ['git', 'commit', '-m', 'Added docs dir.'])
pytest.run(local, ['git', 'push', 'origin', 'master'])
sha = pytest.run(local, ['git', 'rev-parse', 'HEAD']).strip()
target = tmpdir.ensure_dir('target')
target.ensure('docs', '_templates', 'other', 'other.html').write('other')
target.join('docs', '_templates', 'other.html').write('other')
target.ensure('docs', 'other', 'other.py').write('other')
target.join('docs', 'other.rst').write('other')
export(str(local), sha, str(target))
pytest.run(local, ['git', 'diff-index', '--quiet', 'HEAD', '--'])
expected = [
'README',
'docs',
join('docs', '_templates'),
join('docs', '_templates', 'layout.html'),
join('docs', '_templates', 'other'),
join('docs', '_templates', 'other.html'),
join('docs', '_templates', 'other', 'other.html'),
join('docs', 'conf.py'),
join('docs', 'index.rst'),
join('docs', 'other'),
join('docs', 'other.rst'),
join('docs', 'other', 'other.py'),
]
paths = sorted(f.relto(target) for f in target.visit())
assert paths == expected
def test_symlink(tmpdir, local):
"""Test repos with broken symlinks.
:param tmpdir: pytest fixture.
:param local: conftest fixture.
"""
orphan = tmpdir.ensure('to_be_removed')
local.join('good_symlink').mksymlinkto('README')
local.join('broken_symlink').mksymlinkto('to_be_removed')
pytest.run(local, ['git', 'add', 'good_symlink', 'broken_symlink'])
pytest.run(local, ['git', 'commit', '-m', 'Added symlinks.'])
pytest.run(local, ['git', 'push', 'origin', 'master'])
orphan.remove()
target = tmpdir.ensure_dir('target')
sha = pytest.run(local, ['git', 'rev-parse', 'HEAD']).strip()
export(str(local), sha, str(target))
pytest.run(local, ['git', 'diff-index', '--quiet', 'HEAD', '--'
]) # Exit 0 if nothing changed.
files = sorted(f.relto(target) for f in target.listdir())
assert files == ['README', 'good_symlink']
def test_single(tmpdir, local_docs, urls):
"""With single version.
:param tmpdir: pytest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
"""
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
# Run and verify directory.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
actual = sorted(
f.relto(destination) for f in destination.visit() if f.check(dir=True))
expected = [
'.doctrees',
'_sources',
'_static',
'master',
join('master', '.doctrees'),
join('master', '_sources'),
join('master', '_static'),
]
assert actual == expected
# Verify HTML links.
urls(destination.join('contents.html'),
['<li><a href="master/contents.html">master</a></li>'])
urls(destination.join('master', 'contents.html'),
['<li><a href="contents.html">master</a></li>'])
def test_error(tmpdir, config, local_docs, urls, parallel):
"""Test with a bad root ref. Also test skipping bad non-root refs.
:param tmpdir: pytest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
:param bool parallel: Run sphinx-build with -j option.
"""
config.overflow = ('-j', '2') if parallel else tuple()
pytest.run(local_docs, ['git', 'checkout', '-b', 'a_good', 'master'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'c_good', 'master'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'b_broken', 'master'])
local_docs.join('conf.py').write('master_doc = exception\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Broken version.'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'd_broken', 'b_broken'])
pytest.run(local_docs, ['git', 'push', 'origin', 'a_good', 'b_broken', 'c_good', 'd_broken'])
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['b_broken']['sha'], str(exported_root.join(versions['b_broken']['sha'])))
# Bad root ref.
config.root_ref = 'b_broken'
destination = tmpdir.ensure_dir('destination')
with pytest.raises(HandledError):
build_all(str(exported_root), str(destination), versions)
# Remove bad non-root refs.
config.root_ref = 'master'
build_all(str(exported_root), str(destination), versions)
assert [r['name'] for r in versions.remotes] == ['a_good', 'c_good', 'master']
# Verify root HTML links.
urls(destination.join('contents.html'), [
'<li><a href="a_good/contents.html">a_good</a></li>',
'<li><a href="c_good/contents.html">c_good</a></li>',
'<li><a href="master/contents.html">master</a></li>',
])
# Verify a_good links.
urls(destination.join('a_good', 'contents.html'), [
'<li><a href="contents.html">a_good</a></li>',
'<li><a href="../c_good/contents.html">c_good</a></li>',
'<li><a href="../master/contents.html">master</a></li>',
])
# Verify c_good links.
urls(destination.join('c_good', 'contents.html'), [
'<li><a href="../a_good/contents.html">a_good</a></li>',
'<li><a href="contents.html">c_good</a></li>',
'<li><a href="../master/contents.html">master</a></li>',
])
# Verify master links.
urls(destination.join('master', 'contents.html'), [
'<li><a href="../a_good/contents.html">a_good</a></li>',
'<li><a href="../c_good/contents.html">c_good</a></li>',
'<li><a href="contents.html">master</a></li>',
])
def test_banner_tag(tmpdir, banner, config, local_docs, recent):
"""Test banner messages with tags.
:param tmpdir: pytest fixture.
:param banner: conftest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param bool recent: --banner-recent-tag instead of --banner-greatest-tag.
"""
old, new = ('201611', '201612') if recent else ('v1.0.0', 'v2.0.0')
pytest.run(local_docs, ['git', 'tag', old])
pytest.run(local_docs, ['git', 'mv', 'two.rst', 'too.rst'])
local_docs.join('contents.rst').write('Test\n'
'====\n'
'\n'
'Sample documentation.\n'
'\n'
'.. toctree::\n'
' one\n'
' too\n')
local_docs.join('too.rst').write('.. _too:\n'
'\n'
'Too\n'
'===\n'
'\n'
'Sub page documentation 2 too.\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Deleted.'])
pytest.run(local_docs, ['git', 'tag', new])
pytest.run(local_docs, ['git', 'push', 'origin', 'master', old, new])
config.banner_greatest_tag = not recent
config.banner_main_ref = new
config.banner_recent_tag = recent
config.show_banner = True
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
versions['master']['found_docs'] = ('contents', 'one', 'too')
versions[new]['found_docs'] = ('contents', 'one', 'too')
versions[old]['found_docs'] = ('contents', 'one', 'two')
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions[old]['sha'],
str(exported_root.join(versions[old]['sha'])))
# Run and verify files.
dst = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(dst), versions)
actual = sorted(
f.relto(dst) for f in dst.visit(lambda p: p.basename in (
'contents.html', 'one.html', 'two.html', 'too.html')))
expected = [
'contents.html',
join('master', 'contents.html'),
join('master', 'one.html'),
join('master', 'too.html'),
'one.html',
'too.html',
]
if recent:
expected = [
join('201612', 'contents.html'),
join('201612', 'one.html'),
join('201612', 'too.html')
] + expected
expected = [
join('201611', 'contents.html'),
join('201611', 'one.html'),
join('201611', 'two.html')
] + expected
else:
expected += [
join('v1.0.0', 'contents.html'),
join('v1.0.0', 'one.html'),
join('v1.0.0', 'two.html')
]
expected += [
join('v2.0.0', 'contents.html'),
join('v2.0.0', 'one.html'),
join('v2.0.0', 'too.html')
]
assert actual == expected
# Verify master banner.
for page in ('contents', 'one', 'too'):
banner(
dst.join('{}.html'.format(page)),
'{new}/{page}.html'.format(new=new, page=page),
'the development version of Python. The latest version is {}'.
format(new))
banner(
dst.join('master', '{}.html'.format(page)),
'../{new}/{page}.html'.format(new=new, page=page),
'the development version of Python. The latest version is {}'.
format(new))
# Verify old tag banner.
banner(dst.join(old, 'contents.html'), '../{}/contents.html'.format(new),
'an old version of Python. The latest version is {}'.format(new))
banner(dst.join(old, 'one.html'), '../{}/one.html'.format(new),
'an old version of Python. The latest version is {}'.format(new))
banner(dst.join(old, 'two.html'), '', 'an old version of Python')
def test_banner_tag(tmpdir, banner, config, local_docs, recent):
"""Test banner messages with tags.
:param tmpdir: pytest fixture.
:param banner: conftest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param bool recent: --banner-recent-tag instead of --banner-greatest-tag.
"""
old, new = ('201611', '201612') if recent else ('v1.0.0', 'v2.0.0')
pytest.run(local_docs, ['git', 'tag', old])
pytest.run(local_docs, ['git', 'mv', 'two.rst', 'too.rst'])
local_docs.join('contents.rst').write(
'Test\n'
'====\n'
'\n'
'Sample documentation.\n'
'\n'
'.. toctree::\n'
' one\n'
' too\n'
)
local_docs.join('too.rst').write(
'.. _too:\n'
'\n'
'Too\n'
'===\n'
'\n'
'Sub page documentation 2 too.\n'
)
pytest.run(local_docs, ['git', 'commit', '-am', 'Deleted.'])
pytest.run(local_docs, ['git', 'tag', new])
pytest.run(local_docs, ['git', 'push', 'origin', 'master', old, new])
config.banner_greatest_tag = not recent
config.banner_main_ref = new
config.banner_recent_tag = recent
config.show_banner = True
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
versions['master']['found_docs'] = ('contents', 'one', 'too')
versions[new]['found_docs'] = ('contents', 'one', 'too')
versions[old]['found_docs'] = ('contents', 'one', 'two')
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions[old]['sha'], str(exported_root.join(versions[old]['sha'])))
# Run and verify files.
dst = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(dst), versions)
actual = sorted(f.relto(dst)
for f in dst.visit(lambda p: p.basename in ('contents.html', 'one.html', 'two.html', 'too.html')))
expected = [
'contents.html',
join('master', 'contents.html'), join('master', 'one.html'), join('master', 'too.html'),
'one.html',
'too.html',
]
if recent:
expected = [join('201612', 'contents.html'), join('201612', 'one.html'), join('201612', 'too.html')] + expected
expected = [join('201611', 'contents.html'), join('201611', 'one.html'), join('201611', 'two.html')] + expected
else:
expected += [join('v1.0.0', 'contents.html'), join('v1.0.0', 'one.html'), join('v1.0.0', 'two.html')]
expected += [join('v2.0.0', 'contents.html'), join('v2.0.0', 'one.html'), join('v2.0.0', 'too.html')]
assert actual == expected
# Verify master banner.
for page in ('contents', 'one', 'too'):
banner(dst.join('{}.html'.format(page)), '{new}/{page}.html'.format(new=new, page=page),
'the development version of Python. The latest version is {}'.format(new))
banner(dst.join('master', '{}.html'.format(page)), '../{new}/{page}.html'.format(new=new, page=page),
'the development version of Python. The latest version is {}'.format(new))
# Verify old tag banner.
banner(
dst.join(old, 'contents.html'), '../{}/contents.html'.format(new),
'an old version of Python. The latest version is {}'.format(new)
)
banner(
dst.join(old, 'one.html'), '../{}/one.html'.format(new),
'an old version of Python. The latest version is {}'.format(new)
)
banner(dst.join(old, 'two.html'), '', 'an old version of Python')
def test_error(tmpdir, config, local_docs, urls, parallel):
"""Test with a bad root ref. Also test skipping bad non-root refs.
:param tmpdir: pytest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
:param bool parallel: Run sphinx-build with -j option.
"""
config.overflow = ('-j', '2') if parallel else tuple()
pytest.run(local_docs, ['git', 'checkout', '-b', 'a_good', 'master'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'c_good', 'master'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'b_broken', 'master'])
local_docs.join('conf.py').write('master_doc = exception\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Broken version.'])
pytest.run(local_docs, ['git', 'checkout', '-b', 'd_broken', 'b_broken'])
pytest.run(
local_docs,
['git', 'push', 'origin', 'a_good', 'b_broken', 'c_good', 'd_broken'])
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['b_broken']['sha'],
str(exported_root.join(versions['b_broken']['sha'])))
# Bad root ref.
config.root_ref = 'b_broken'
destination = tmpdir.ensure_dir('destination')
with pytest.raises(HandledError):
build_all(str(exported_root), str(destination), versions)
# Remove bad non-root refs.
config.root_ref = 'master'
build_all(str(exported_root), str(destination), versions)
assert [r['name']
for r in versions.remotes] == ['a_good', 'c_good', 'master']
# Verify root HTML links.
urls(destination.join('contents.html'), [
'<li><a href="a_good/contents.html">a_good</a></li>',
'<li><a href="c_good/contents.html">c_good</a></li>',
'<li><a href="master/contents.html">master</a></li>',
])
# Verify a_good links.
urls(destination.join('a_good', 'contents.html'), [
'<li><a href="contents.html">a_good</a></li>',
'<li><a href="../c_good/contents.html">c_good</a></li>',
'<li><a href="../master/contents.html">master</a></li>',
])
# Verify c_good links.
urls(destination.join('c_good', 'contents.html'), [
'<li><a href="../a_good/contents.html">a_good</a></li>',
'<li><a href="contents.html">c_good</a></li>',
'<li><a href="../master/contents.html">master</a></li>',
])
# Verify master links.
urls(destination.join('master', 'contents.html'), [
'<li><a href="../a_good/contents.html">a_good</a></li>',
'<li><a href="../c_good/contents.html">c_good</a></li>',
'<li><a href="contents.html">master</a></li>',
])
def test_multiple(tmpdir, config, local_docs, urls, triple, parallel):
"""With two or three versions.
:param tmpdir: pytest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
:param bool triple: With three versions (including master) instead of two.
:param bool parallel: Run sphinx-build with -j option.
"""
config.overflow = ('-j', '2') if parallel else tuple()
pytest.run(local_docs, ['git', 'tag', 'v1.0.0'])
pytest.run(local_docs, ['git', 'push', 'origin', 'v1.0.0'])
if triple:
pytest.run(local_docs, ['git', 'tag', 'v1.0.1'])
pytest.run(local_docs, ['git', 'push', 'origin', 'v1.0.1'])
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export (git tags point to same master sha).
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
# Run and verify directory.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
actual = sorted(
f.relto(destination) for f in destination.visit() if f.check(dir=True))
expected = [
'.doctrees',
'_sources',
'_static',
'master',
join('master', '.doctrees'),
join('master', '_sources'),
join('master', '_static'),
'v1.0.0',
join('v1.0.0', '.doctrees'),
join('v1.0.0', '_sources'),
join('v1.0.0', '_static'),
]
if triple:
expected.extend([
'v1.0.1',
join('v1.0.1', '.doctrees'),
join('v1.0.1', '_sources'),
join('v1.0.1', '_static'),
])
assert actual == expected
# Verify root HTML links.
expected = [
'<li><a href="master/contents.html">master</a></li>',
'<li><a href="v1.0.0/contents.html">v1.0.0</a></li>',
]
if triple:
expected.append('<li><a href="v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('contents.html'), expected)
# Verify master links.
expected = [
'<li><a href="contents.html">master</a></li>',
'<li><a href="../v1.0.0/contents.html">v1.0.0</a></li>'
]
if triple:
expected.append(
'<li><a href="../v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('master', 'contents.html'), expected)
# Verify v1.0.0 links.
expected = [
'<li><a href="../master/contents.html">master</a></li>',
'<li><a href="contents.html">v1.0.0</a></li>'
]
if triple:
expected.append(
'<li><a href="../v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('v1.0.0', 'contents.html'), expected)
if not triple:
return
# Verify v1.0.1 links.
urls(destination.join('v1.0.1', 'contents.html'), [
'<li><a href="../master/contents.html">master</a></li>',
'<li><a href="../v1.0.0/contents.html">v1.0.0</a></li>',
'<li><a href="contents.html">v1.0.1</a></li>',
])
def test_multiple(tmpdir, config, local_docs, urls, triple, parallel):
"""With two or three versions.
:param tmpdir: pytest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param urls: conftest fixture.
:param bool triple: With three versions (including master) instead of two.
:param bool parallel: Run sphinx-build with -j option.
"""
config.overflow = ('-j', '2') if parallel else tuple()
pytest.run(local_docs, ['git', 'tag', 'v1.0.0'])
pytest.run(local_docs, ['git', 'push', 'origin', 'v1.0.0'])
if triple:
pytest.run(local_docs, ['git', 'tag', 'v1.0.1'])
pytest.run(local_docs, ['git', 'push', 'origin', 'v1.0.1'])
versions = Versions(gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
# Export (git tags point to same master sha).
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'], str(exported_root.join(versions['master']['sha'])))
# Run and verify directory.
destination = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(destination), versions)
actual = sorted(f.relto(destination) for f in destination.visit() if f.check(dir=True))
expected = [
'.doctrees',
'_sources',
'_static',
'master',
join('master', '.doctrees'),
join('master', '_sources'),
join('master', '_static'),
'v1.0.0',
join('v1.0.0', '.doctrees'),
join('v1.0.0', '_sources'),
join('v1.0.0', '_static'),
]
if triple:
expected.extend([
'v1.0.1',
join('v1.0.1', '.doctrees'),
join('v1.0.1', '_sources'),
join('v1.0.1', '_static'),
])
assert actual == expected
# Verify root HTML links.
expected = [
'<li><a href="master/contents.html">master</a></li>',
'<li><a href="v1.0.0/contents.html">v1.0.0</a></li>',
]
if triple:
expected.append('<li><a href="v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('contents.html'), expected)
# Verify master links.
expected = ['<li><a href="contents.html">master</a></li>', '<li><a href="../v1.0.0/contents.html">v1.0.0</a></li>']
if triple:
expected.append('<li><a href="../v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('master', 'contents.html'), expected)
# Verify v1.0.0 links.
expected = ['<li><a href="../master/contents.html">master</a></li>', '<li><a href="contents.html">v1.0.0</a></li>']
if triple:
expected.append('<li><a href="../v1.0.1/contents.html">v1.0.1</a></li>')
urls(destination.join('v1.0.0', 'contents.html'), expected)
if not triple:
return
# Verify v1.0.1 links.
urls(destination.join('v1.0.1', 'contents.html'), [
'<li><a href="../master/contents.html">master</a></li>',
'<li><a href="../v1.0.0/contents.html">v1.0.0</a></li>',
'<li><a href="contents.html">v1.0.1</a></li>',
])
def test_banner_branch(tmpdir, banner, config, local_docs, show_banner):
"""Test banner messages without tags.
:param tmpdir: pytest fixture.
:param banner: conftest fixture.
:param config: conftest fixture.
:param local_docs: conftest fixture.
:param bool show_banner: Show the banner.
"""
pytest.run(local_docs, ['git', 'checkout', '-b', 'old_build', 'master'])
pytest.run(local_docs, ['git', 'checkout', 'master'])
pytest.run(local_docs, ['git', 'rm', 'two.rst'])
local_docs.join('contents.rst').write('Test\n'
'====\n'
'\n'
'Sample documentation.\n'
'\n'
'.. toctree::\n'
' one\n')
pytest.run(local_docs, ['git', 'commit', '-am', 'Deleted.'])
pytest.run(local_docs, ['git', 'push', 'origin', 'master', 'old_build'])
config.show_banner = show_banner
versions = Versions(
gather_git_info(str(local_docs), ['conf.py'], tuple(), tuple()))
versions['master']['found_docs'] = ('contents', 'one')
versions['old_build']['found_docs'] = ('contents', 'one', 'two')
# Export.
exported_root = tmpdir.ensure_dir('exported_root')
export(str(local_docs), versions['master']['sha'],
str(exported_root.join(versions['master']['sha'])))
export(str(local_docs), versions['old_build']['sha'],
str(exported_root.join(versions['old_build']['sha'])))
# Run and verify files.
dst = tmpdir.ensure_dir('destination')
build_all(str(exported_root), str(dst), versions)
actual = sorted(
f.relto(dst) for f in dst.visit(
lambda p: p.basename in ('contents.html', 'one.html', 'two.html')))
expected = [
'contents.html',
join('master', 'contents.html'),
join('master', 'one.html'),
join('old_build', 'contents.html'),
join('old_build', 'one.html'),
join('old_build', 'two.html'), 'one.html'
]
assert actual == expected
# Verify no banner.
if not show_banner:
for path in expected:
banner(dst.join(path), None)
return
for path in ('contents.html', 'master/contents.html', 'master/one.html',
'one.html'):
banner(dst.join(path), None)
# Verify banner.
banner(dst.join('old_build', 'contents.html'), '../master/contents.html',
'the development version of Python. The main version is master')
banner(dst.join('old_build', 'one.html'), '../master/one.html',
'the development version of Python. The main version is master')
banner(dst.join('old_build', 'two.html'), '',
'the development version of Python')
