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