diff options
Diffstat (limited to 'tests/test_builders')
26 files changed, 6144 insertions, 0 deletions
diff --git a/tests/test_builders/__init__.py b/tests/test_builders/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tests/test_builders/__init__.py diff --git a/tests/test_builders/conftest.py b/tests/test_builders/conftest.py new file mode 100644 index 0000000..1203d5d --- /dev/null +++ b/tests/test_builders/conftest.py @@ -0,0 +1,28 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING + +import pytest + +from sphinx.testing.util import etree_parse + +if TYPE_CHECKING: + from collections.abc import Callable, Iterator + from pathlib import Path + from xml.etree.ElementTree import ElementTree + +_etree_cache: dict[Path, ElementTree] = {} + + +def _parse(path: Path) -> ElementTree: + if path in _etree_cache: + return _etree_cache[path] + + _etree_cache[path] = tree = etree_parse(path) + return tree + + +@pytest.fixture(scope='package') +def cached_etree_parse() -> Iterator[Callable[[Path], ElementTree]]: + yield _parse + _etree_cache.clear() diff --git a/tests/test_builders/test_build.py b/tests/test_builders/test_build.py new file mode 100644 index 0000000..3f6d12c --- /dev/null +++ b/tests/test_builders/test_build.py @@ -0,0 +1,165 @@ +"""Test all builders.""" + +import os +import shutil +from contextlib import contextmanager +from unittest import mock + +import pytest +from docutils import nodes + +from sphinx.cmd.build import build_main +from sphinx.errors import SphinxError + +from tests.utils import TESTS_ROOT + + +def request_session_head(url, **kwargs): + response = mock.Mock() + response.status_code = 200 + response.url = url + return response + + +@pytest.fixture() +def nonascii_srcdir(request, rootdir, sphinx_test_tempdir): + # Build in a non-ASCII source dir + test_name = '\u65e5\u672c\u8a9e' + basedir = sphinx_test_tempdir / request.node.originalname + srcdir = basedir / test_name + if not srcdir.exists(): + shutil.copytree(rootdir / 'test-root', srcdir) + + # add a doc with a non-ASCII file name to the source dir + (srcdir / (test_name + '.txt')).write_text(""" +nonascii file name page +======================= +""", encoding='utf8') + + root_doc = srcdir / 'index.txt' + root_doc.write_text(root_doc.read_text(encoding='utf8') + f""" +.. toctree:: + +{test_name}/{test_name} +""", encoding='utf8') + return srcdir + + +# note: this test skips building docs for some builders because they have independent testcase. +# (html, changes, epub, latex, texinfo and manpage) +@pytest.mark.parametrize( + "buildername", + ['dirhtml', 'singlehtml', 'text', 'xml', 'pseudoxml', 'linkcheck'], +) +@mock.patch('sphinx.builders.linkcheck.requests.head', + side_effect=request_session_head) +def test_build_all(requests_head, make_app, nonascii_srcdir, buildername): + app = make_app(buildername, srcdir=nonascii_srcdir) + app.build() + + +def test_root_doc_not_found(tmp_path, make_app): + (tmp_path / 'conf.py').write_text('', encoding='utf8') + assert os.listdir(tmp_path) == ['conf.py'] + + app = make_app('dummy', srcdir=tmp_path) + with pytest.raises(SphinxError): + app.build(force_all=True) # no index.rst + + +@pytest.mark.sphinx(buildername='text', testroot='circular') +def test_circular_toctree(app, status, warning): + app.build(force_all=True) + warnings = warning.getvalue() + assert ( + 'circular toctree references detected, ignoring: ' + 'sub <- index <- sub') in warnings + assert ( + 'circular toctree references detected, ignoring: ' + 'index <- sub <- index') in warnings + + +@pytest.mark.sphinx(buildername='text', testroot='numbered-circular') +def test_numbered_circular_toctree(app, status, warning): + app.build(force_all=True) + warnings = warning.getvalue() + assert ( + 'circular toctree references detected, ignoring: ' + 'sub <- index <- sub') in warnings + assert ( + 'circular toctree references detected, ignoring: ' + 'index <- sub <- index') in warnings + + +@pytest.mark.sphinx(buildername='dummy', testroot='images') +def test_image_glob(app, status, warning): + app.build(force_all=True) + + # index.rst + doctree = app.env.get_doctree('index') + + assert isinstance(doctree[0][1], nodes.image) + assert doctree[0][1]['candidates'] == {'*': 'rimg.png'} + assert doctree[0][1]['uri'] == 'rimg.png' + + assert isinstance(doctree[0][2], nodes.figure) + assert isinstance(doctree[0][2][0], nodes.image) + assert doctree[0][2][0]['candidates'] == {'*': 'rimg.png'} + assert doctree[0][2][0]['uri'] == 'rimg.png' + + assert isinstance(doctree[0][3], nodes.image) + assert doctree[0][3]['candidates'] == {'application/pdf': 'img.pdf', + 'image/gif': 'img.gif', + 'image/png': 'img.png'} + assert doctree[0][3]['uri'] == 'img.*' + + assert isinstance(doctree[0][4], nodes.figure) + assert isinstance(doctree[0][4][0], nodes.image) + assert doctree[0][4][0]['candidates'] == {'application/pdf': 'img.pdf', + 'image/gif': 'img.gif', + 'image/png': 'img.png'} + assert doctree[0][4][0]['uri'] == 'img.*' + + # subdir/index.rst + doctree = app.env.get_doctree('subdir/index') + + assert isinstance(doctree[0][1], nodes.image) + assert doctree[0][1]['candidates'] == {'*': 'subdir/rimg.png'} + assert doctree[0][1]['uri'] == 'subdir/rimg.png' + + assert isinstance(doctree[0][2], nodes.image) + assert doctree[0][2]['candidates'] == {'application/pdf': 'subdir/svgimg.pdf', + 'image/svg+xml': 'subdir/svgimg.svg'} + assert doctree[0][2]['uri'] == 'subdir/svgimg.*' + + assert isinstance(doctree[0][3], nodes.figure) + assert isinstance(doctree[0][3][0], nodes.image) + assert doctree[0][3][0]['candidates'] == {'application/pdf': 'subdir/svgimg.pdf', + 'image/svg+xml': 'subdir/svgimg.svg'} + assert doctree[0][3][0]['uri'] == 'subdir/svgimg.*' + + +@contextmanager +def force_colors(): + forcecolor = os.environ.get('FORCE_COLOR', None) + + try: + os.environ['FORCE_COLOR'] = '1' + yield + finally: + if forcecolor is None: + os.environ.pop('FORCE_COLOR', None) + else: + os.environ['FORCE_COLOR'] = forcecolor + + +def test_log_no_ansi_colors(tmp_path): + with force_colors(): + wfile = tmp_path / 'warnings.txt' + srcdir = TESTS_ROOT / 'roots' / 'test-nitpicky-warnings' + argv = list(map(str, ['-b', 'html', srcdir, tmp_path, '-n', '-w', wfile])) + retcode = build_main(argv) + assert retcode == 0 + + content = wfile.read_text(encoding='utf8') + assert '\x1b[91m' not in content diff --git a/tests/test_builders/test_build_changes.py b/tests/test_builders/test_build_changes.py new file mode 100644 index 0000000..b537b87 --- /dev/null +++ b/tests/test_builders/test_build_changes.py @@ -0,0 +1,34 @@ +"""Test the ChangesBuilder class.""" + +import pytest + + +@pytest.mark.sphinx('changes', testroot='changes') +def test_build(app): + app.build() + + # TODO: Use better checking of html content + htmltext = (app.outdir / 'changes.html').read_text(encoding='utf8') + assert 'Added in version 0.6: Some funny stuff.' in htmltext + assert 'Changed in version 0.6: Even more funny stuff.' in htmltext + assert 'Deprecated since version 0.6: Boring stuff.' in htmltext + + path_html = ( + '<b>Path</b>: <i>deprecated:</i> Deprecated since version 0.6:' + ' So, that was a bad idea it turns out.') + assert path_html in htmltext + + malloc_html = ( + '<b>void *Test_Malloc(size_t n)</b>: <i>changed:</i> Changed in version 0.6:' + ' Can now be replaced with a different allocator.</a>') + assert malloc_html in htmltext + + +@pytest.mark.sphinx( + 'changes', testroot='changes', srcdir='changes-none', + confoverrides={'version': '0.7', 'release': '0.7b1'}) +def test_no_changes(app, status): + app.build() + + assert 'no changes in version 0.7.' in status.getvalue() + assert not (app.outdir / 'changes.html').exists() diff --git a/tests/test_builders/test_build_dirhtml.py b/tests/test_builders/test_build_dirhtml.py new file mode 100644 index 0000000..dc5ab86 --- /dev/null +++ b/tests/test_builders/test_build_dirhtml.py @@ -0,0 +1,40 @@ +"""Test dirhtml builder.""" + +import posixpath + +import pytest + +from sphinx.util.inventory import InventoryFile + + +@pytest.mark.sphinx(buildername='dirhtml', testroot='builder-dirhtml') +def test_dirhtml(app, status, warning): + app.build() + + assert (app.outdir / 'index.html').exists() + assert (app.outdir / 'foo/index.html').exists() + assert (app.outdir / 'foo/foo_1/index.html').exists() + assert (app.outdir / 'foo/foo_2/index.html').exists() + assert (app.outdir / 'bar/index.html').exists() + + content = (app.outdir / 'index.html').read_text(encoding='utf8') + assert 'href="foo/"' in content + assert 'href="foo/foo_1/"' in content + assert 'href="foo/foo_2/"' in content + assert 'href="bar/"' in content + + # objects.inv (refs: #7095) + with (app.outdir / 'objects.inv').open('rb') as f: + invdata = InventoryFile.load(f, 'path/to', posixpath.join) + + assert 'index' in invdata.get('std:doc') + assert invdata['std:doc']['index'] == ('Python', '', 'path/to/', '-') + + assert 'foo/index' in invdata.get('std:doc') + assert invdata['std:doc']['foo/index'] == ('Python', '', 'path/to/foo/', '-') + + assert 'index' in invdata.get('std:label') + assert invdata['std:label']['index'] == ('Python', '', 'path/to/#index', '-') + + assert 'foo' in invdata.get('std:label') + assert invdata['std:label']['foo'] == ('Python', '', 'path/to/foo/#foo', 'foo/index') diff --git a/tests/test_builders/test_build_epub.py b/tests/test_builders/test_build_epub.py new file mode 100644 index 0000000..6829f22 --- /dev/null +++ b/tests/test_builders/test_build_epub.py @@ -0,0 +1,417 @@ +"""Test the HTML builder and check output against XPath.""" + +import os +import subprocess +from pathlib import Path +from subprocess import CalledProcessError +from xml.etree import ElementTree + +import pytest + +from sphinx.builders.epub3 import _XML_NAME_PATTERN + + +# check given command is runnable +def runnable(command): + try: + subprocess.run(command, capture_output=True, check=True) + return True + except (OSError, CalledProcessError): + return False # command not found or exit with non-zero + + +class EPUBElementTree: + """Test helper for content.opf and toc.ncx""" + + namespaces = { + 'idpf': 'http://www.idpf.org/2007/opf', + 'dc': 'http://purl.org/dc/elements/1.1/', + 'ibooks': 'http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/', + 'ncx': 'http://www.daisy.org/z3986/2005/ncx/', + 'xhtml': 'http://www.w3.org/1999/xhtml', + 'epub': 'http://www.idpf.org/2007/ops', + } + + def __init__(self, tree): + self.tree = tree + + @classmethod + def fromstring(cls, string): + tree = ElementTree.fromstring(string) # NoQA: S314 # using known data in tests + return cls(tree) + + def find(self, match): + ret = self.tree.find(match, namespaces=self.namespaces) + if ret is not None: + return self.__class__(ret) + else: + return ret + + def findall(self, match): + ret = self.tree.findall(match, namespaces=self.namespaces) + return [self.__class__(e) for e in ret] + + def __getattr__(self, name): + return getattr(self.tree, name) + + def __iter__(self): + for child in self.tree: + yield self.__class__(child) + + +@pytest.mark.sphinx('epub', testroot='basic') +def test_build_epub(app): + app.build(force_all=True) + assert (app.outdir / 'mimetype').read_text(encoding='utf8') == 'application/epub+zip' + assert (app.outdir / 'META-INF' / 'container.xml').exists() + + # toc.ncx + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_text(encoding='utf8')) + assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' + + # toc.ncx / head + meta = list(toc.find("./ncx:head")) + assert meta[0].attrib == {'name': 'dtb:uid', 'content': 'unknown'} + assert meta[1].attrib == {'name': 'dtb:depth', 'content': '1'} + assert meta[2].attrib == {'name': 'dtb:totalPageCount', 'content': '0'} + assert meta[3].attrib == {'name': 'dtb:maxPageNumber', 'content': '0'} + + # toc.ncx / navMap + navpoints = toc.findall("./ncx:navMap/ncx:navPoint") + assert len(navpoints) == 1 + assert navpoints[0].attrib == {'id': 'navPoint1', 'playOrder': '1'} + assert navpoints[0].find("./ncx:content").attrib == {'src': 'index.xhtml'} + + navlabel = navpoints[0].find("./ncx:navLabel/ncx:text") + assert navlabel.text == 'The basic Sphinx documentation for testing' + + # content.opf + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text(encoding='utf8')) + + # content.opf / metadata + metadata = opf.find("./idpf:metadata") + assert metadata.find("./dc:language").text == 'en' + assert metadata.find("./dc:title").text == 'Python' + assert metadata.find("./dc:description").text == 'unknown' + assert metadata.find("./dc:creator").text == 'unknown' + assert metadata.find("./dc:contributor").text == 'unknown' + assert metadata.find("./dc:publisher").text == 'unknown' + assert metadata.find("./dc:rights").text is None + assert metadata.find("./idpf:meta[@property='ibooks:version']").text is None + assert metadata.find("./idpf:meta[@property='ibooks:specified-fonts']").text == 'true' + assert metadata.find("./idpf:meta[@property='ibooks:binding']").text == 'true' + assert metadata.find("./idpf:meta[@property='ibooks:scroll-axis']").text == 'vertical' + + # content.opf / manifest + manifest = opf.find("./idpf:manifest") + items = list(manifest) + assert items[0].attrib == {'id': 'ncx', + 'href': 'toc.ncx', + 'media-type': 'application/x-dtbncx+xml'} + assert items[1].attrib == {'id': 'nav', + 'href': 'nav.xhtml', + 'media-type': 'application/xhtml+xml', + 'properties': 'nav'} + assert items[2].attrib == {'id': 'epub-0', + 'href': 'genindex.xhtml', + 'media-type': 'application/xhtml+xml'} + assert items[3].attrib == {'id': 'epub-1', + 'href': 'index.xhtml', + 'media-type': 'application/xhtml+xml'} + + for i, item in enumerate(items[2:]): + # items are named as epub-NN + assert item.get('id') == 'epub-%d' % i + + # content.opf / spine + spine = opf.find("./idpf:spine") + itemrefs = list(spine) + assert spine.get('toc') == 'ncx' + assert spine.get('page-progression-direction') == 'ltr' + assert itemrefs[0].get('idref') == 'epub-1' + assert itemrefs[1].get('idref') == 'epub-0' + + # content.opf / guide + reference = opf.find("./idpf:guide/idpf:reference") + assert reference.get('type') == 'toc' + assert reference.get('title') == 'Table of Contents' + assert reference.get('href') == 'index.xhtml' + + # nav.xhtml + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_text(encoding='utf8')) + assert nav.attrib == {'lang': 'en', + '{http://www.w3.org/XML/1998/namespace}lang': 'en'} + assert nav.find("./xhtml:head/xhtml:title").text == 'Table of Contents' + + # nav.xhtml / nav + navlist = nav.find("./xhtml:body/xhtml:nav") + toc = navlist.findall("./xhtml:ol/xhtml:li") + assert navlist.find("./xhtml:h1").text == 'Table of Contents' + assert len(toc) == 1 + assert toc[0].find("./xhtml:a").get("href") == 'index.xhtml' + assert toc[0].find("./xhtml:a").text == 'The basic Sphinx documentation for testing' + + +@pytest.mark.sphinx('epub', testroot='footnotes', + confoverrides={'epub_cover': ('_images/rimg.png', None)}) +def test_epub_cover(app): + app.build() + + # content.opf / metadata + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text(encoding='utf8')) + cover_image = opf.find("./idpf:manifest/idpf:item[@href='%s']" % app.config.epub_cover[0]) + cover = opf.find("./idpf:metadata/idpf:meta[@name='cover']") + assert cover + assert cover.get('content') == cover_image.get('id') + + +@pytest.mark.sphinx('epub', testroot='toctree') +def test_nested_toc(app): + app.build() + + # toc.ncx + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_bytes()) + assert toc.find("./ncx:docTitle/ncx:text").text == 'Python' + + # toc.ncx / navPoint + def navinfo(elem): + label = elem.find("./ncx:navLabel/ncx:text") + content = elem.find("./ncx:content") + return (elem.get('id'), elem.get('playOrder'), + content.get('src'), label.text) + + navpoints = toc.findall("./ncx:navMap/ncx:navPoint") + assert len(navpoints) == 4 + assert navinfo(navpoints[0]) == ('navPoint1', '1', 'index.xhtml', + "Welcome to Sphinx Tests’s documentation!") + assert navpoints[0].findall("./ncx:navPoint") == [] + + # toc.ncx / nested navPoints + assert navinfo(navpoints[1]) == ('navPoint2', '2', 'foo.xhtml', 'foo') + navchildren = navpoints[1].findall("./ncx:navPoint") + assert len(navchildren) == 4 + assert navinfo(navchildren[0]) == ('navPoint3', '2', 'foo.xhtml', 'foo') + assert navinfo(navchildren[1]) == ('navPoint4', '3', 'quux.xhtml', 'quux') + assert navinfo(navchildren[2]) == ('navPoint5', '4', 'foo.xhtml#foo-1', 'foo.1') + assert navinfo(navchildren[3]) == ('navPoint8', '6', 'foo.xhtml#foo-2', 'foo.2') + + # nav.xhtml / nav + def navinfo(elem): + anchor = elem.find("./xhtml:a") + return (anchor.get('href'), anchor.text) + + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_bytes()) + toc = nav.findall("./xhtml:body/xhtml:nav/xhtml:ol/xhtml:li") + assert len(toc) == 4 + assert navinfo(toc[0]) == ('index.xhtml', + "Welcome to Sphinx Tests’s documentation!") + assert toc[0].findall("./xhtml:ol") == [] + + # nav.xhtml / nested toc + assert navinfo(toc[1]) == ('foo.xhtml', 'foo') + tocchildren = toc[1].findall("./xhtml:ol/xhtml:li") + assert len(tocchildren) == 3 + assert navinfo(tocchildren[0]) == ('quux.xhtml', 'quux') + assert navinfo(tocchildren[1]) == ('foo.xhtml#foo-1', 'foo.1') + assert navinfo(tocchildren[2]) == ('foo.xhtml#foo-2', 'foo.2') + + grandchild = tocchildren[1].findall("./xhtml:ol/xhtml:li") + assert len(grandchild) == 1 + assert navinfo(grandchild[0]) == ('foo.xhtml#foo-1-1', 'foo.1-1') + + +@pytest.mark.sphinx('epub', testroot='need-escaped') +def test_escaped_toc(app): + app.build() + + # toc.ncx + toc = EPUBElementTree.fromstring((app.outdir / 'toc.ncx').read_bytes()) + assert toc.find("./ncx:docTitle/ncx:text").text == 'need <b>"escaped"</b> project' + + # toc.ncx / navPoint + def navinfo(elem): + label = elem.find("./ncx:navLabel/ncx:text") + content = elem.find("./ncx:content") + return (elem.get('id'), elem.get('playOrder'), + content.get('src'), label.text) + + navpoints = toc.findall("./ncx:navMap/ncx:navPoint") + assert len(navpoints) == 4 + assert navinfo(navpoints[0]) == ('navPoint1', '1', 'index.xhtml', + "Welcome to Sphinx Tests's documentation!") + assert navpoints[0].findall("./ncx:navPoint") == [] + + # toc.ncx / nested navPoints + assert navinfo(navpoints[1]) == ('navPoint2', '2', 'foo.xhtml', '<foo>') + navchildren = navpoints[1].findall("./ncx:navPoint") + assert len(navchildren) == 4 + assert navinfo(navchildren[0]) == ('navPoint3', '2', 'foo.xhtml', '<foo>') + assert navinfo(navchildren[1]) == ('navPoint4', '3', 'quux.xhtml', 'quux') + assert navinfo(navchildren[2]) == ('navPoint5', '4', 'foo.xhtml#foo-1', 'foo “1”') + assert navinfo(navchildren[3]) == ('navPoint8', '6', 'foo.xhtml#foo-2', 'foo.2') + + # nav.xhtml / nav + def navinfo(elem): + anchor = elem.find("./xhtml:a") + return (anchor.get('href'), anchor.text) + + nav = EPUBElementTree.fromstring((app.outdir / 'nav.xhtml').read_bytes()) + toc = nav.findall("./xhtml:body/xhtml:nav/xhtml:ol/xhtml:li") + assert len(toc) == 4 + assert navinfo(toc[0]) == ('index.xhtml', + "Welcome to Sphinx Tests's documentation!") + assert toc[0].findall("./xhtml:ol") == [] + + # nav.xhtml / nested toc + assert navinfo(toc[1]) == ('foo.xhtml', '<foo>') + tocchildren = toc[1].findall("./xhtml:ol/xhtml:li") + assert len(tocchildren) == 3 + assert navinfo(tocchildren[0]) == ('quux.xhtml', 'quux') + assert navinfo(tocchildren[1]) == ('foo.xhtml#foo-1', 'foo “1”') + assert navinfo(tocchildren[2]) == ('foo.xhtml#foo-2', 'foo.2') + + grandchild = tocchildren[1].findall("./xhtml:ol/xhtml:li") + assert len(grandchild) == 1 + assert navinfo(grandchild[0]) == ('foo.xhtml#foo-1-1', 'foo.1-1') + + +@pytest.mark.sphinx('epub', testroot='basic') +def test_epub_writing_mode(app): + # horizontal (default) + app.build(force_all=True) + + # horizontal / page-progression-direction + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text(encoding='utf8')) + assert opf.find("./idpf:spine").get('page-progression-direction') == 'ltr' + + # horizontal / ibooks:scroll-axis + metadata = opf.find("./idpf:metadata") + assert metadata.find("./idpf:meta[@property='ibooks:scroll-axis']").text == 'vertical' + + # horizontal / writing-mode (CSS) + css = (app.outdir / '_static' / 'epub.css').read_text(encoding='utf8') + assert 'writing-mode: horizontal-tb;' in css + + # vertical + app.config.epub_writing_mode = 'vertical' + (app.outdir / 'index.xhtml').unlink() # forcely rebuild + app.build() + + # vertical / page-progression-direction + opf = EPUBElementTree.fromstring((app.outdir / 'content.opf').read_text(encoding='utf8')) + assert opf.find("./idpf:spine").get('page-progression-direction') == 'rtl' + + # vertical / ibooks:scroll-axis + metadata = opf.find("./idpf:metadata") + assert metadata.find("./idpf:meta[@property='ibooks:scroll-axis']").text == 'horizontal' + + # vertical / writing-mode (CSS) + css = (app.outdir / '_static' / 'epub.css').read_text(encoding='utf8') + assert 'writing-mode: vertical-rl;' in css + + +@pytest.mark.sphinx('epub', testroot='epub-anchor-id') +def test_epub_anchor_id(app): + app.build() + + html = (app.outdir / 'index.xhtml').read_text(encoding='utf8') + assert ('<p id="std-setting-STATICFILES_FINDERS">' + 'blah blah blah</p>' in html) + assert ('<span id="std-setting-STATICFILES_SECTION"></span>' + '<h1>blah blah blah</h1>' in html) + assert 'see <a class="reference internal" href="#std-setting-STATICFILES_FINDERS">' in html + + +@pytest.mark.sphinx('epub', testroot='html_assets') +def test_epub_assets(app): + app.build(force_all=True) + + # epub_sytlesheets (same as html_css_files) + content = (app.outdir / 'index.xhtml').read_text(encoding='utf8') + assert ('<link rel="stylesheet" type="text/css" href="_static/css/style.css" />' + in content) + assert ('<link media="print" rel="stylesheet" title="title" type="text/css" ' + 'href="https://example.com/custom.css" />' in content) + + +@pytest.mark.sphinx('epub', testroot='html_assets', + confoverrides={'epub_css_files': ['css/epub.css']}) +def test_epub_css_files(app): + app.build(force_all=True) + + # epub_css_files + content = (app.outdir / 'index.xhtml').read_text(encoding='utf8') + assert '<link rel="stylesheet" type="text/css" href="_static/css/epub.css" />' in content + + # files in html_css_files are not outputted + assert ('<link rel="stylesheet" type="text/css" href="_static/css/style.css" />' + not in content) + assert ('<link media="print" rel="stylesheet" title="title" type="text/css" ' + 'href="https://example.com/custom.css" />' not in content) + + +@pytest.mark.sphinx('epub', testroot='roles-download') +def test_html_download_role(app, status, warning): + app.build() + assert not (app.outdir / '_downloads' / 'dummy.dat').exists() + + content = (app.outdir / 'index.xhtml').read_text(encoding='utf8') + assert ('<li><p><code class="xref download docutils literal notranslate">' + '<span class="pre">dummy.dat</span></code></p></li>' in content) + assert ('<li><p><code class="xref download docutils literal notranslate">' + '<span class="pre">not_found.dat</span></code></p></li>' in content) + assert ('<li><p><code class="xref download docutils literal notranslate">' + '<span class="pre">Sphinx</span> <span class="pre">logo</span></code>' + '<span class="link-target"> [https://www.sphinx-doc.org/en/master' + '/_static/sphinx-logo.svg]</span></p></li>' in content) + + +@pytest.mark.sphinx('epub', testroot='toctree-duplicated') +def test_duplicated_toctree_entry(app, status, warning): + app.build(force_all=True) + assert 'WARNING: duplicated ToC entry found: foo.xhtml' in warning.getvalue() + + +@pytest.mark.skipif('DO_EPUBCHECK' not in os.environ, + reason='Skipped because DO_EPUBCHECK is not set') +@pytest.mark.sphinx('epub') +def test_run_epubcheck(app): + app.build() + + if not runnable(['java', '-version']): + pytest.skip("Unable to run Java; skipping test") + + epubcheck = os.environ.get('EPUBCHECK_PATH', '/usr/share/java/epubcheck.jar') + if not os.path.exists(epubcheck): + pytest.skip("Could not find epubcheck; skipping test") + + try: + subprocess.run(['java', '-jar', epubcheck, app.outdir / 'SphinxTests.epub'], + capture_output=True, check=True) + except CalledProcessError as exc: + print(exc.stdout.decode('utf-8')) + print(exc.stderr.decode('utf-8')) + msg = f'epubcheck exited with return code {exc.returncode}' + raise AssertionError(msg) from exc + + +def test_xml_name_pattern_check(): + assert _XML_NAME_PATTERN.match('id-pub') + assert _XML_NAME_PATTERN.match('webpage') + assert not _XML_NAME_PATTERN.match('1bfda21') + + +@pytest.mark.sphinx('epub', testroot='images') +def test_copy_images(app, status, warning): + app.build() + + images_dir = Path(app.outdir) / '_images' + images = {image.name for image in images_dir.rglob('*')} + images.discard('python-logo.png') + assert images == { + 'img.png', + 'rimg.png', + 'rimg1.png', + 'svgimg.svg', + 'testimäge.png', + } diff --git a/tests/test_builders/test_build_gettext.py b/tests/test_builders/test_build_gettext.py new file mode 100644 index 0000000..ddc6d30 --- /dev/null +++ b/tests/test_builders/test_build_gettext.py @@ -0,0 +1,235 @@ +"""Test the build process with gettext builder with the test root.""" + +import gettext +import os +import re +import subprocess +import sys +from subprocess import CalledProcessError + +import pytest + +from sphinx.builders.gettext import Catalog, MsgOrigin + +if sys.version_info[:2] >= (3, 11): + from contextlib import chdir +else: + from sphinx.util.osutil import _chdir as chdir + +_MSGID_PATTERN = re.compile(r'msgid "(.*)"') + + +def msgid_getter(msgid): + if m := _MSGID_PATTERN.search(msgid): + return m[1] + return None + + +def test_Catalog_duplicated_message(): + catalog = Catalog() + catalog.add('hello', MsgOrigin('/path/to/filename', 1)) + catalog.add('hello', MsgOrigin('/path/to/filename', 1)) + catalog.add('hello', MsgOrigin('/path/to/filename', 2)) + catalog.add('hello', MsgOrigin('/path/to/yetanother', 1)) + catalog.add('world', MsgOrigin('/path/to/filename', 1)) + + assert len(list(catalog)) == 2 + + msg1, msg2 = list(catalog) + assert msg1.text == 'hello' + assert msg1.locations == [('/path/to/filename', 1), + ('/path/to/filename', 2), + ('/path/to/yetanother', 1)] + assert msg2.text == 'world' + assert msg2.locations == [('/path/to/filename', 1)] + + +@pytest.mark.sphinx('gettext', srcdir='root-gettext') +def test_build_gettext(app): + # Generic build; should fail only when the builder is horribly broken. + app.build(force_all=True) + + # Do messages end up in the correct location? + # top-level documents end up in a message catalog + assert (app.outdir / 'extapi.pot').is_file() + # directory items are grouped into sections + assert (app.outdir / 'subdir.pot').is_file() + + # regression test for issue #960 + catalog = (app.outdir / 'markup.pot').read_text(encoding='utf8') + assert 'msgid "something, something else, something more"' in catalog + + +@pytest.mark.sphinx('gettext', srcdir='root-gettext') +def test_msgfmt(app): + app.build(force_all=True) + + (app.outdir / 'en' / 'LC_MESSAGES').mkdir(parents=True, exist_ok=True) + with chdir(app.outdir): + try: + args = ['msginit', '--no-translator', '-i', 'markup.pot', '--locale', 'en_US'] + subprocess.run(args, capture_output=True, check=True) + except OSError: + pytest.skip() # most likely msginit was not found + except CalledProcessError as exc: + print(exc.stdout) + print(exc.stderr) + msg = f'msginit exited with return code {exc.returncode}' + raise AssertionError(msg) from exc + + assert (app.outdir / 'en_US.po').is_file(), 'msginit failed' + try: + args = ['msgfmt', 'en_US.po', + '-o', os.path.join('en', 'LC_MESSAGES', 'test_root.mo')] + subprocess.run(args, capture_output=True, check=True) + except OSError: + pytest.skip() # most likely msgfmt was not found + except CalledProcessError as exc: + print(exc.stdout) + print(exc.stderr) + msg = f'msgfmt exited with return code {exc.returncode}' + raise AssertionError(msg) from exc + + mo = app.outdir / 'en' / 'LC_MESSAGES' / 'test_root.mo' + assert mo.is_file(), 'msgfmt failed' + + _ = gettext.translation('test_root', app.outdir, languages=['en']).gettext + assert _("Testing various markup") == "Testing various markup" + + +@pytest.mark.sphinx( + 'gettext', testroot='intl', srcdir='gettext', + confoverrides={'gettext_compact': False}) +def test_gettext_index_entries(app): + # regression test for #976 + app.build(filenames=[app.srcdir / 'index_entries.txt']) + + pot = (app.outdir / 'index_entries.pot').read_text(encoding='utf8') + msg_ids = list(filter(None, map(msgid_getter, pot.splitlines()))) + + assert msg_ids == [ + "i18n with index entries", + "index target section", + "this is :index:`Newsletter` target paragraph.", + "various index entries", + "That's all.", + "Mailing List", + "Newsletter", + "Recipients List", + "First", + "Second", + "Third", + "Entry", + "See", + ] + + +@pytest.mark.sphinx( + 'gettext', testroot='intl', srcdir='gettext', + confoverrides={'gettext_compact': False, + 'gettext_additional_targets': []}) +def test_gettext_disable_index_entries(app): + # regression test for #976 + app.env._pickled_doctree_cache.clear() # clear cache + app.build(filenames=[app.srcdir / 'index_entries.txt']) + + pot = (app.outdir / 'index_entries.pot').read_text(encoding='utf8') + msg_ids = list(filter(None, map(msgid_getter, pot.splitlines()))) + + assert msg_ids == [ + "i18n with index entries", + "index target section", + "this is :index:`Newsletter` target paragraph.", + "various index entries", + "That's all.", + ] + + +@pytest.mark.sphinx('gettext', testroot='intl', srcdir='gettext') +def test_gettext_template(app): + app.build(force_all=True) + + assert (app.outdir / 'sphinx.pot').is_file() + + result = (app.outdir / 'sphinx.pot').read_text(encoding='utf8') + assert "Welcome" in result + assert "Sphinx %(version)s" in result + + +@pytest.mark.sphinx('gettext', testroot='gettext-template') +def test_gettext_template_msgid_order_in_sphinxpot(app): + app.build(force_all=True) + assert (app.outdir / 'sphinx.pot').is_file() + + result = (app.outdir / 'sphinx.pot').read_text(encoding='utf8') + assert re.search( + ('msgid "Template 1".*' + 'msgid "This is Template 1\\.".*' + 'msgid "Template 2".*' + 'msgid "This is Template 2\\.".*'), + result, + flags=re.DOTALL) + + +@pytest.mark.sphinx( + 'gettext', srcdir='root-gettext', + confoverrides={'gettext_compact': 'documentation'}) +def test_build_single_pot(app): + app.build(force_all=True) + + assert (app.outdir / 'documentation.pot').is_file() + + result = (app.outdir / 'documentation.pot').read_text(encoding='utf8') + assert re.search( + ('msgid "Todo".*' + 'msgid "Like footnotes.".*' + 'msgid "The minute.".*' + 'msgid "Generated section".*'), + result, + flags=re.DOTALL) + + +@pytest.mark.sphinx( + 'gettext', + testroot='intl_substitution_definitions', + srcdir='gettext-subst', + confoverrides={'gettext_compact': False, + 'gettext_additional_targets': ['image']}) +def test_gettext_prolog_epilog_substitution(app): + app.build(force_all=True) + + assert (app.outdir / 'prolog_epilog_substitution.pot').is_file() + pot = (app.outdir / 'prolog_epilog_substitution.pot').read_text(encoding='utf8') + msg_ids = list(filter(None, map(msgid_getter, pot.splitlines()))) + + assert msg_ids == [ + "i18n with prologue and epilogue substitutions", + "This is content that contains |subst_prolog_1|.", + "Substituted image |subst_prolog_2| here.", + "subst_prolog_2", + ".. image:: /img.png", + "This is content that contains |subst_epilog_1|.", + "Substituted image |subst_epilog_2| here.", + "subst_epilog_2", + ".. image:: /i18n.png", + ] + + +@pytest.mark.sphinx( + 'gettext', + testroot='intl_substitution_definitions', + srcdir='gettext-subst', + confoverrides={'gettext_compact': False, + 'gettext_additional_targets': ['image']}) +def test_gettext_prolog_epilog_substitution_excluded(app): + # regression test for #9428 + app.build(force_all=True) + + assert (app.outdir / 'prolog_epilog_substitution_excluded.pot').is_file() + pot = (app.outdir / 'prolog_epilog_substitution_excluded.pot').read_text(encoding='utf8') + msg_ids = list(filter(None, map(msgid_getter, pot.splitlines()))) + + assert msg_ids == [ + "i18n without prologue and epilogue substitutions", + "This is content that does not include prologue and epilogue substitutions.", + ] diff --git a/tests/test_builders/test_build_html.py b/tests/test_builders/test_build_html.py new file mode 100644 index 0000000..1fa3ba4 --- /dev/null +++ b/tests/test_builders/test_build_html.py @@ -0,0 +1,378 @@ +"""Test the HTML builder and check output against XPath.""" + +import os +import posixpath +import re + +import pytest + +from sphinx.builders.html import validate_html_extra_path, validate_html_static_path +from sphinx.deprecation import RemovedInSphinx80Warning +from sphinx.errors import ConfigError +from sphinx.util.console import strip_colors +from sphinx.util.inventory import InventoryFile + +from tests.test_builders.xpath_data import FIGURE_CAPTION +from tests.test_builders.xpath_util import check_xpath + + +def test_html4_error(make_app, tmp_path): + (tmp_path / 'conf.py').write_text('', encoding='utf-8') + with pytest.raises( + ConfigError, + match='HTML 4 is no longer supported by Sphinx', + ): + make_app( + buildername='html', + srcdir=tmp_path, + confoverrides={'html4_writer': True}, + ) + + +@pytest.mark.parametrize(("fname", "path", "check"), [ + ('index.html', ".//div[@class='citation']/span", r'Ref1'), + ('index.html', ".//div[@class='citation']/span", r'Ref_1'), + + ('footnote.html', ".//a[@class='footnote-reference brackets'][@href='#id9'][@id='id1']", r"1"), + ('footnote.html', ".//a[@class='footnote-reference brackets'][@href='#id10'][@id='id2']", r"2"), + ('footnote.html', ".//a[@class='footnote-reference brackets'][@href='#foo'][@id='id3']", r"3"), + ('footnote.html', ".//a[@class='reference internal'][@href='#bar'][@id='id4']/span", r"\[bar\]"), + ('footnote.html', ".//a[@class='reference internal'][@href='#baz-qux'][@id='id5']/span", r"\[baz_qux\]"), + ('footnote.html', ".//a[@class='footnote-reference brackets'][@href='#id11'][@id='id6']", r"4"), + ('footnote.html', ".//a[@class='footnote-reference brackets'][@href='#id12'][@id='id7']", r"5"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id1']", r"1"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id2']", r"2"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id3']", r"3"), + ('footnote.html', ".//div[@class='citation']/span/a[@href='#id4']", r"bar"), + ('footnote.html', ".//div[@class='citation']/span/a[@href='#id5']", r"baz_qux"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id6']", r"4"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id7']", r"5"), + ('footnote.html', ".//aside[@class='footnote brackets']/span/a[@href='#id8']", r"6"), +]) +@pytest.mark.sphinx('html') +@pytest.mark.test_params(shared_result='test_build_html_output_docutils18') +def test_docutils_output(app, cached_etree_parse, fname, path, check): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check) + + +@pytest.mark.sphinx('html', parallel=2) +def test_html_parallel(app): + app.build() + + +@pytest.mark.sphinx('html', testroot='build-html-translator') +def test_html_translator(app): + app.build() + assert app.builder.docwriter.visitor.depart_with_node == 10 + + +@pytest.mark.parametrize("expect", [ + (FIGURE_CAPTION + "//span[@class='caption-number']", "Fig. 1", True), + (FIGURE_CAPTION + "//span[@class='caption-number']", "Fig. 2", True), + (FIGURE_CAPTION + "//span[@class='caption-number']", "Fig. 3", True), + (".//div//span[@class='caption-number']", "No.1 ", True), + (".//div//span[@class='caption-number']", "No.2 ", True), + (".//li/p/a/span", 'Fig. 1', True), + (".//li/p/a/span", 'Fig. 2', True), + (".//li/p/a/span", 'Fig. 3', True), + (".//li/p/a/span", 'No.1', True), + (".//li/p/a/span", 'No.2', True), +]) +@pytest.mark.sphinx('html', testroot='add_enumerable_node', + srcdir='test_enumerable_node') +def test_enumerable_node(app, cached_etree_parse, expect): + app.build() + check_xpath(cached_etree_parse(app.outdir / 'index.html'), 'index.html', *expect) + + +@pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_copy_source': False}) +def test_html_copy_source(app): + app.build(force_all=True) + assert not (app.outdir / '_sources' / 'index.rst.txt').exists() + + +@pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_sourcelink_suffix': '.txt'}) +def test_html_sourcelink_suffix(app): + app.build(force_all=True) + assert (app.outdir / '_sources' / 'index.rst.txt').exists() + + +@pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_sourcelink_suffix': '.rst'}) +def test_html_sourcelink_suffix_same(app): + app.build(force_all=True) + assert (app.outdir / '_sources' / 'index.rst').exists() + + +@pytest.mark.sphinx('html', testroot='basic', confoverrides={'html_sourcelink_suffix': ''}) +def test_html_sourcelink_suffix_empty(app): + app.build(force_all=True) + assert (app.outdir / '_sources' / 'index.rst').exists() + + +@pytest.mark.sphinx('html', testroot='html_entity') +def test_html_entity(app): + app.build(force_all=True) + valid_entities = {'amp', 'lt', 'gt', 'quot', 'apos'} + content = (app.outdir / 'index.html').read_text(encoding='utf8') + for entity in re.findall(r'&([a-z]+);', content, re.MULTILINE): + assert entity not in valid_entities + + +@pytest.mark.sphinx('html', testroot='basic') +def test_html_inventory(app): + app.build(force_all=True) + + with app.outdir.joinpath('objects.inv').open('rb') as f: + invdata = InventoryFile.load(f, 'https://www.google.com', posixpath.join) + + assert set(invdata.keys()) == {'std:label', 'std:doc'} + assert set(invdata['std:label'].keys()) == {'modindex', + 'py-modindex', + 'genindex', + 'search'} + assert invdata['std:label']['modindex'] == ('Python', + '', + 'https://www.google.com/py-modindex.html', + 'Module Index') + assert invdata['std:label']['py-modindex'] == ('Python', + '', + 'https://www.google.com/py-modindex.html', + 'Python Module Index') + assert invdata['std:label']['genindex'] == ('Python', + '', + 'https://www.google.com/genindex.html', + 'Index') + assert invdata['std:label']['search'] == ('Python', + '', + 'https://www.google.com/search.html', + 'Search Page') + assert set(invdata['std:doc'].keys()) == {'index'} + assert invdata['std:doc']['index'] == ('Python', + '', + 'https://www.google.com/index.html', + 'The basic Sphinx documentation for testing') + + +@pytest.mark.sphinx('html', testroot='images', confoverrides={'html_sourcelink_suffix': ''}) +def test_html_anchor_for_figure(app): + app.build(force_all=True) + content = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<figcaption>\n<p><span class="caption-text">The caption of pic</span>' + '<a class="headerlink" href="#id1" title="Link to this image">¶</a></p>\n</figcaption>' + in content) + + +@pytest.mark.sphinx('html', testroot='directives-raw') +def test_html_raw_directive(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'index.html').read_text(encoding='utf8') + + # standard case + assert 'standalone raw directive (HTML)' in result + assert 'standalone raw directive (LaTeX)' not in result + + # with substitution + assert '<p>HTML: abc def ghi</p>' in result + assert '<p>LaTeX: abc ghi</p>' in result + + +@pytest.mark.parametrize("expect", [ + (".//link[@href='_static/persistent.css']" + "[@rel='stylesheet']", '', True), + (".//link[@href='_static/default.css']" + "[@rel='stylesheet']" + "[@title='Default']", '', True), + (".//link[@href='_static/alternate1.css']" + "[@rel='alternate stylesheet']" + "[@title='Alternate']", '', True), + (".//link[@href='_static/alternate2.css']" + "[@rel='alternate stylesheet']", '', True), + (".//link[@href='_static/more_persistent.css']" + "[@rel='stylesheet']", '', True), + (".//link[@href='_static/more_default.css']" + "[@rel='stylesheet']" + "[@title='Default']", '', True), + (".//link[@href='_static/more_alternate1.css']" + "[@rel='alternate stylesheet']" + "[@title='Alternate']", '', True), + (".//link[@href='_static/more_alternate2.css']" + "[@rel='alternate stylesheet']", '', True), +]) +@pytest.mark.sphinx('html', testroot='stylesheets') +def test_alternate_stylesheets(app, cached_etree_parse, expect): + app.build() + check_xpath(cached_etree_parse(app.outdir / 'index.html'), 'index.html', *expect) + + +@pytest.mark.sphinx('html', testroot='html_style') +def test_html_style(app, status, warning): + app.build() + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert '<link rel="stylesheet" type="text/css" href="_static/default.css" />' in result + assert ('<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />' + not in result) + + +@pytest.mark.sphinx('html', testroot='basic') +def test_html_sidebar(app, status, warning): + ctx = {} + + # default for alabaster + app.build(force_all=True) + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<div class="sphinxsidebar" role="navigation" ' + 'aria-label="main navigation">' in result) + assert '<h1 class="logo"><a href="#">Python</a></h1>' in result + assert '<h3>Navigation</h3>' in result + assert '<h3>Related Topics</h3>' in result + assert '<h3 id="searchlabel">Quick search</h3>' in result + + app.builder.add_sidebars('index', ctx) + assert ctx['sidebars'] == ['about.html', 'navigation.html', 'relations.html', + 'searchbox.html', 'donate.html'] + + # only relations.html + app.config.html_sidebars = {'**': ['relations.html']} + app.build(force_all=True) + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<div class="sphinxsidebar" role="navigation" ' + 'aria-label="main navigation">' in result) + assert '<h1 class="logo"><a href="#">Python</a></h1>' not in result + assert '<h3>Navigation</h3>' not in result + assert '<h3>Related Topics</h3>' in result + assert '<h3 id="searchlabel">Quick search</h3>' not in result + + app.builder.add_sidebars('index', ctx) + assert ctx['sidebars'] == ['relations.html'] + + # no sidebars + app.config.html_sidebars = {'**': []} + app.build(force_all=True) + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<div class="sphinxsidebar" role="navigation" ' + 'aria-label="main navigation">' not in result) + assert '<h1 class="logo"><a href="#">Python</a></h1>' not in result + assert '<h3>Navigation</h3>' not in result + assert '<h3>Related Topics</h3>' not in result + assert '<h3 id="searchlabel">Quick search</h3>' not in result + + app.builder.add_sidebars('index', ctx) + assert ctx['sidebars'] == [] + + +@pytest.mark.parametrize(("fname", "expect"), [ + ('index.html', (".//h1/em/a[@href='https://example.com/cp.1']", '', True)), + ('index.html', (".//em/a[@href='https://example.com/man.1']", '', True)), + ('index.html', (".//em/a[@href='https://example.com/ls.1']", '', True)), + ('index.html', (".//em/a[@href='https://example.com/sphinx.']", '', True)), +]) +@pytest.mark.sphinx('html', testroot='manpage_url', confoverrides={ + 'manpages_url': 'https://example.com/{page}.{section}'}) +@pytest.mark.test_params(shared_result='test_build_html_manpage_url') +def test_html_manpage(app, cached_etree_parse, fname, expect): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect) + + +@pytest.mark.sphinx('html', testroot='toctree-glob', + confoverrides={'html_baseurl': 'https://example.com/'}) +def test_html_baseurl(app, status, warning): + app.build() + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert '<link rel="canonical" href="https://example.com/index.html" />' in result + + result = (app.outdir / 'qux' / 'index.html').read_text(encoding='utf8') + assert '<link rel="canonical" href="https://example.com/qux/index.html" />' in result + + +@pytest.mark.sphinx('html', testroot='toctree-glob', + confoverrides={'html_baseurl': 'https://example.com/subdir', + 'html_file_suffix': '.htm'}) +def test_html_baseurl_and_html_file_suffix(app, status, warning): + app.build() + + result = (app.outdir / 'index.htm').read_text(encoding='utf8') + assert '<link rel="canonical" href="https://example.com/subdir/index.htm" />' in result + + result = (app.outdir / 'qux' / 'index.htm').read_text(encoding='utf8') + assert '<link rel="canonical" href="https://example.com/subdir/qux/index.htm" />' in result + + +@pytest.mark.sphinx(testroot='basic', srcdir='validate_html_extra_path') +def test_validate_html_extra_path(app): + (app.confdir / '_static').mkdir(parents=True, exist_ok=True) + app.config.html_extra_path = [ + '/path/to/not_found', # not found + '_static', + app.outdir, # outdir + app.outdir / '_static', # inside outdir + ] + with pytest.warns(RemovedInSphinx80Warning, match='Use "pathlib.Path" or "os.fspath" instead'): + validate_html_extra_path(app, app.config) + assert app.config.html_extra_path == ['_static'] + + +@pytest.mark.sphinx(testroot='basic', srcdir='validate_html_static_path') +def test_validate_html_static_path(app): + (app.confdir / '_static').mkdir(parents=True, exist_ok=True) + app.config.html_static_path = [ + '/path/to/not_found', # not found + '_static', + app.outdir, # outdir + app.outdir / '_static', # inside outdir + ] + with pytest.warns(RemovedInSphinx80Warning, match='Use "pathlib.Path" or "os.fspath" instead'): + validate_html_static_path(app, app.config) + assert app.config.html_static_path == ['_static'] + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'html_permalinks': False}) +def test_html_permalink_disable(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert '<h1>The basic Sphinx documentation for testing</h1>' in content + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'html_permalinks_icon': '<span>[PERMALINK]</span>'}) +def test_html_permalink_icon(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert ('<h1>The basic Sphinx documentation for testing<a class="headerlink" ' + 'href="#the-basic-sphinx-documentation-for-testing" ' + 'title="Link to this heading"><span>[PERMALINK]</span></a></h1>' in content) + + +@pytest.mark.sphinx('html', testroot='html_signaturereturn_icon') +def test_html_signaturereturn_icon(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert ('<span class="sig-return-icon">→</span>' in content) + + +@pytest.mark.sphinx('html', testroot='root', srcdir=os.urandom(4).hex()) +def test_html_remove_sources_before_write_gh_issue_10786(app, warning): + # see: https://github.com/sphinx-doc/sphinx/issues/10786 + target = app.srcdir / 'img.png' + + def handler(app): + assert target.exists() + target.unlink() + return [] + + app.connect('html-collect-pages', handler) + assert target.exists() + app.build() + assert not target.exists() + + ws = strip_colors(warning.getvalue()).splitlines() + assert len(ws) >= 1 + + file = os.fsdecode(target) + assert f'WARNING: cannot copy image file {file!r}: {file!s} does not exist' == ws[-1] diff --git a/tests/test_builders/test_build_html_5_output.py b/tests/test_builders/test_build_html_5_output.py new file mode 100644 index 0000000..ece6f49 --- /dev/null +++ b/tests/test_builders/test_build_html_5_output.py @@ -0,0 +1,276 @@ +"""Test the HTML builder and check output against XPath.""" + +import re + +import pytest + +from tests.test_builders.xpath_util import check_xpath + + +def tail_check(check): + rex = re.compile(check) + + def checker(nodes): + for node in nodes: + if node.tail and rex.search(node.tail): + return True + msg = f'{check!r} not found in tail of any nodes {nodes}' + raise AssertionError(msg) + return checker + + +@pytest.mark.parametrize(("fname", "path", "check"), [ + ('images.html', ".//img[@src='_images/img.png']", ''), + ('images.html', ".//img[@src='_images/img1.png']", ''), + ('images.html', ".//img[@src='_images/simg.png']", ''), + ('images.html', ".//img[@src='_images/svgimg.svg']", ''), + ('images.html', ".//a[@href='_sources/images.txt']", ''), + + ('subdir/images.html', ".//img[@src='../_images/img1.png']", ''), + ('subdir/images.html', ".//img[@src='../_images/rimg.png']", ''), + + ('subdir/includes.html', ".//a[@class='reference download internal']", ''), + ('subdir/includes.html', ".//img[@src='../_images/img.png']", ''), + ('subdir/includes.html', ".//p", 'This is an include file.'), + ('subdir/includes.html', ".//pre/span", 'line 1'), + ('subdir/includes.html', ".//pre/span", 'line 2'), + + ('includes.html', ".//pre", 'Max Strauß'), + ('includes.html', ".//a[@class='reference download internal']", ''), + ('includes.html', ".//pre/span", '"quotes"'), + ('includes.html', ".//pre/span", "'included'"), + ('includes.html', ".//pre/span[@class='s2']", 'üöä'), + ('includes.html', ".//div[@class='inc-pyobj1 highlight-text notranslate']//pre", + r'^class Foo:\n pass\n\s*$'), + ('includes.html', ".//div[@class='inc-pyobj2 highlight-text notranslate']//pre", + r'^ def baz\(\):\n pass\n\s*$'), + ('includes.html', ".//div[@class='inc-lines highlight-text notranslate']//pre", + r'^class Foo:\n pass\nclass Bar:\n$'), + ('includes.html', ".//div[@class='inc-startend highlight-text notranslate']//pre", + '^foo = "Including Unicode characters: üöä"\\n$'), + ('includes.html', ".//div[@class='inc-preappend highlight-text notranslate']//pre", + r'(?m)^START CODE$'), + ('includes.html', ".//div[@class='inc-pyobj-dedent highlight-python notranslate']//span", + r'def'), + ('includes.html', ".//div[@class='inc-tab3 highlight-text notranslate']//pre", + r'-| |-'), + ('includes.html', ".//div[@class='inc-tab8 highlight-python notranslate']//pre/span", + r'-| |-'), + + ('autodoc.html', ".//dl[@class='py class']/dt[@id='autodoc_target.Class']", ''), + ('autodoc.html', ".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span/span", r'\*\*'), + ('autodoc.html', ".//dl[@class='py function']/dt[@id='autodoc_target.function']/em/span/span", r'kwds'), + ('autodoc.html', ".//dd/p", r'Return spam\.'), + + ('extapi.html', ".//strong", 'from class: Bar'), + + ('markup.html', ".//title", 'set by title directive'), + ('markup.html', ".//p/em", 'Section author: Georg Brandl'), + ('markup.html', ".//p/em", 'Module author: Georg Brandl'), + # created by the meta directive + ('markup.html', ".//meta[@name='author'][@content='Me']", ''), + ('markup.html', ".//meta[@name='keywords'][@content='docs, sphinx']", ''), + # a label created by ``.. _label:`` + ('markup.html', ".//div[@id='label']", ''), + # code with standard code blocks + ('markup.html', ".//pre", '^some code$'), + # an option list + ('markup.html', ".//span[@class='option']", '--help'), + # admonitions + ('markup.html', ".//p[@class='admonition-title']", 'My Admonition'), + ('markup.html', ".//div[@class='admonition note']/p", 'Note text.'), + ('markup.html', ".//div[@class='admonition warning']/p", 'Warning text.'), + # inline markup + ('markup.html', ".//li/p/strong", r'^command\\n$'), + ('markup.html', ".//li/p/strong", r'^program\\n$'), + ('markup.html', ".//li/p/em", r'^dfn\\n$'), + ('markup.html', ".//li/p/kbd", r'^kbd\\n$'), + ('markup.html', ".//li/p/span", 'File \N{TRIANGULAR BULLET} Close'), + ('markup.html', ".//li/p/code/span[@class='pre']", '^a/$'), + ('markup.html', ".//li/p/code/em/span[@class='pre']", '^varpart$'), + ('markup.html', ".//li/p/code/em/span[@class='pre']", '^i$'), + ('markup.html', ".//a[@href='https://peps.python.org/pep-0008/']" + "[@class='pep reference external']/strong", 'PEP 8'), + ('markup.html', ".//a[@href='https://peps.python.org/pep-0008/']" + "[@class='pep reference external']/strong", + 'Python Enhancement Proposal #8'), + ('markup.html', ".//a[@href='https://datatracker.ietf.org/doc/html/rfc1.html']" + "[@class='rfc reference external']/strong", 'RFC 1'), + ('markup.html', ".//a[@href='https://datatracker.ietf.org/doc/html/rfc1.html']" + "[@class='rfc reference external']/strong", 'Request for Comments #1'), + ('markup.html', ".//a[@href='objects.html#envvar-HOME']" + "[@class='reference internal']/code/span[@class='pre']", 'HOME'), + ('markup.html', ".//a[@href='#with']" + "[@class='reference internal']/code/span[@class='pre']", '^with$'), + ('markup.html', ".//a[@href='#grammar-token-try_stmt']" + "[@class='reference internal']/code/span", '^statement$'), + ('markup.html', ".//a[@href='#some-label'][@class='reference internal']/span", '^here$'), + ('markup.html', ".//a[@href='#some-label'][@class='reference internal']/span", '^there$'), + ('markup.html', ".//a[@href='subdir/includes.html']" + "[@class='reference internal']/span", 'Including in subdir'), + ('markup.html', ".//a[@href='objects.html#cmdoption-python-c']" + "[@class='reference internal']/code/span[@class='pre']", '-c'), + # abbreviations + ('markup.html', ".//abbr[@title='abbreviation']", '^abbr$'), + # version stuff + ('markup.html', ".//div[@class='versionadded']/p/span", 'Added in version 0.6: '), + ('markup.html', ".//div[@class='versionadded']/p/span", + tail_check('First paragraph of versionadded')), + ('markup.html', ".//div[@class='versionchanged']/p/span", + tail_check('First paragraph of versionchanged')), + ('markup.html', ".//div[@class='versionchanged']/p", + 'Second paragraph of versionchanged'), + ('markup.html', ".//div[@class='versionremoved']/p/span", 'Removed in version 0.6: '), + # footnote reference + ('markup.html', ".//a[@class='footnote-reference brackets']", r'1'), + # created by reference lookup + ('markup.html', ".//a[@href='index.html#ref1']", ''), + # ``seealso`` directive + ('markup.html', ".//div/p[@class='admonition-title']", 'See also'), + # a ``hlist`` directive + ('markup.html', ".//table[@class='hlist']/tr/td/ul/li/p", '^This$'), + # a ``centered`` directive + ('markup.html', ".//p[@class='centered']/strong", 'LICENSE'), + # a glossary + ('markup.html', ".//dl/dt[@id='term-boson']", 'boson'), + ('markup.html', ".//dl/dt[@id='term-boson']/a", '¶'), + # a production list + ('markup.html', ".//pre/strong", 'try_stmt'), + ('markup.html', ".//pre/a[@href='#grammar-token-try1_stmt']/code/span", 'try1_stmt'), + # tests for ``only`` directive + ('markup.html', ".//p", 'A global substitution!'), + ('markup.html', ".//p", 'In HTML.'), + ('markup.html', ".//p", 'In both.'), + ('markup.html', ".//p", 'Always present'), + # tests for ``any`` role + ('markup.html', ".//a[@href='#with']/span", 'headings'), + ('markup.html', ".//a[@href='objects.html#func_without_body']/code/span", 'objects'), + # tests for numeric labels + ('markup.html', ".//a[@href='#id1'][@class='reference internal']/span", 'Testing various markup'), + # tests for smartypants + ('markup.html', ".//li/p", 'Smart “quotes” in English ‘text’.'), + ('markup.html', ".//li/p", 'Smart — long and – short dashes.'), + ('markup.html', ".//li/p", 'Ellipsis…'), + ('markup.html', ".//li/p/code/span[@class='pre']", 'foo--"bar"...'), + ('markup.html', ".//p", 'Этот «абзац» должен использовать „русские“ кавычки.'), + ('markup.html', ".//p", 'Il dit : « C’est “super” ! »'), + + ('objects.html', ".//dt[@id='mod.Cls.meth1']", ''), + ('objects.html', ".//dt[@id='errmod.Error']", ''), + ('objects.html', ".//dt/span[@class='sig-name descname']/span[@class='pre']", r'long\(parameter,'), + ('objects.html', ".//dt/span[@class='sig-name descname']/span[@class='pre']", r'list\)'), + ('objects.html', ".//dt/span[@class='sig-name descname']/span[@class='pre']", 'another'), + ('objects.html', ".//dt/span[@class='sig-name descname']/span[@class='pre']", 'one'), + ('objects.html', ".//a[@href='#mod.Cls'][@class='reference internal']", ''), + ('objects.html', ".//dl[@class='std userdesc']", ''), + ('objects.html', ".//dt[@id='userdesc-myobj']", ''), + ('objects.html', ".//a[@href='#userdesc-myobj'][@class='reference internal']", ''), + # docfields + ('objects.html', ".//a[@class='reference internal'][@href='#TimeInt']/em", 'TimeInt'), + ('objects.html', ".//a[@class='reference internal'][@href='#Time']", 'Time'), + ('objects.html', ".//a[@class='reference internal'][@href='#errmod.Error']/strong", 'Error'), + # C references + ('objects.html', ".//span[@class='pre']", 'CFunction()'), + ('objects.html', ".//a[@href='#c.Sphinx_DoSomething']", ''), + ('objects.html', ".//a[@href='#c.SphinxStruct.member']", ''), + ('objects.html', ".//a[@href='#c.SPHINX_USE_PYTHON']", ''), + ('objects.html', ".//a[@href='#c.SphinxType']", ''), + ('objects.html', ".//a[@href='#c.sphinx_global']", ''), + # test global TOC created by toctree() + ('objects.html', ".//ul[@class='current']/li[@class='toctree-l1 current']/a[@href='#']", + 'Testing object descriptions'), + ('objects.html', ".//li[@class='toctree-l1']/a[@href='markup.html']", + 'Testing various markup'), + # test unknown field names + ('objects.html', ".//dt[@class='field-odd']", 'Field_name'), + ('objects.html', ".//dt[@class='field-even']", 'Field_name all lower'), + ('objects.html', ".//dt[@class='field-odd']", 'FIELD_NAME'), + ('objects.html', ".//dt[@class='field-even']", 'FIELD_NAME ALL CAPS'), + ('objects.html', ".//dt[@class='field-odd']", 'Field_Name'), + ('objects.html', ".//dt[@class='field-even']", 'Field_Name All Word Caps'), + # ('objects.html', ".//dt[@class='field-odd']", 'Field_name'), (duplicate) + ('objects.html', ".//dt[@class='field-even']", 'Field_name First word cap'), + ('objects.html', ".//dt[@class='field-odd']", 'FIELd_name'), + ('objects.html', ".//dt[@class='field-even']", 'FIELd_name PARTial caps'), + # custom sidebar + ('objects.html', ".//h4", 'Custom sidebar'), + # docfields + ('objects.html', ".//dd[@class='field-odd']/p/strong", '^moo$'), + ('objects.html', ".//dd[@class='field-odd']/p/strong", tail_check(r'\(Moo\) .* Moo')), + ('objects.html', ".//dd[@class='field-odd']/ul/li/p/strong", '^hour$'), + ('objects.html', ".//dd[@class='field-odd']/ul/li/p/em", '^DuplicateType$'), + ('objects.html', ".//dd[@class='field-odd']/ul/li/p/em", tail_check(r'.* Some parameter')), + # others + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-arg-p']/code/span", + 'perl'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-arg-p']/code/span", + '\\+p'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-ObjC']/code/span", + '--ObjC\\+\\+'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-plugin.option']/code/span", + '--plugin.option'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-arg-create-auth-token']" + "/code/span", + 'create-auth-token'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-arg-arg']/code/span", + 'arg'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-perl-j']/code/span", + '-j'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-hg-arg-commit']/code/span", + 'hg'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-hg-arg-commit']/code/span", + 'commit'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-git-commit-p']/code/span", + 'git'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-git-commit-p']/code/span", + 'commit'), + ('objects.html', ".//a[@class='reference internal'][@href='#cmdoption-git-commit-p']/code/span", + '-p'), + + ('index.html', ".//meta[@name='hc'][@content='hcval']", ''), + ('index.html', ".//meta[@name='hc_co'][@content='hcval_co']", ''), + ('index.html', ".//li[@class='toctree-l1']/a", 'Testing various markup'), + ('index.html', ".//li[@class='toctree-l2']/a", 'Inline markup'), + ('index.html', ".//title", 'Sphinx <Tests>'), + ('index.html', ".//div[@class='footer']", 'copyright text credits'), + ('index.html', ".//a[@href='https://python.org/']" + "[@class='reference external']", ''), + ('index.html', ".//li/p/a[@href='genindex.html']/span", 'Index'), + ('index.html', ".//li/p/a[@href='py-modindex.html']/span", 'Module Index'), + # custom sidebar only for contents + ('index.html', ".//h4", 'Contents sidebar'), + # custom JavaScript + ('index.html', ".//script[@src='file://moo.js']", ''), + # URL in contents + ('index.html', ".//a[@class='reference external'][@href='https://sphinx-doc.org/']", + 'https://sphinx-doc.org/'), + ('index.html', ".//a[@class='reference external'][@href='https://sphinx-doc.org/latest/']", + 'Latest reference'), + # Indirect hyperlink targets across files + ('index.html', ".//a[@href='markup.html#some-label'][@class='reference internal']/span", + '^indirect hyperref$'), + + ('bom.html', ".//title", " File with UTF-8 BOM"), + + ('extensions.html', ".//a[@href='https://python.org/dev/']", "https://python.org/dev/"), + ('extensions.html', ".//a[@href='https://bugs.python.org/issue1000']", "issue 1000"), + ('extensions.html', ".//a[@href='https://bugs.python.org/issue1042']", "explicit caption"), + + # index entries + ('genindex.html', ".//a/strong", "Main"), + ('genindex.html', ".//a/strong", "[1]"), + ('genindex.html', ".//a/strong", "Other"), + ('genindex.html', ".//a", "entry"), + ('genindex.html', ".//li/a", "double"), + + ('otherext.html', ".//h1", "Generated section"), + ('otherext.html', ".//a[@href='_sources/otherext.foo.txt']", ''), + + ('search.html', ".//meta[@name='robots'][@content='noindex']", ''), +]) +@pytest.mark.sphinx('html', tags=['testtag'], + confoverrides={'html_context.hckey_co': 'hcval_co'}) +@pytest.mark.test_params(shared_result='test_build_html_output') +def test_html5_output(app, cached_etree_parse, fname, path, check): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check) diff --git a/tests/test_builders/test_build_html_assets.py b/tests/test_builders/test_build_html_assets.py new file mode 100644 index 0000000..fc7a987 --- /dev/null +++ b/tests/test_builders/test_build_html_assets.py @@ -0,0 +1,152 @@ +"""Test the HTML builder and check output against XPath.""" + +import re +from pathlib import Path + +import pytest + +import sphinx.builders.html +from sphinx.builders.html._assets import _file_checksum +from sphinx.errors import ThemeError + + +@pytest.mark.sphinx('html', testroot='html_assets') +def test_html_assets(app): + app.build(force_all=True) + + # exclude_path and its family + assert not (app.outdir / 'static' / 'index.html').exists() + assert not (app.outdir / 'extra' / 'index.html').exists() + + # html_static_path + assert not (app.outdir / '_static' / '.htaccess').exists() + assert not (app.outdir / '_static' / '.htpasswd').exists() + assert (app.outdir / '_static' / 'API.html').exists() + assert (app.outdir / '_static' / 'API.html').read_text(encoding='utf8') == 'Sphinx-1.4.4' + assert (app.outdir / '_static' / 'css' / 'style.css').exists() + assert (app.outdir / '_static' / 'js' / 'custom.js').exists() + assert (app.outdir / '_static' / 'rimg.png').exists() + assert not (app.outdir / '_static' / '_build' / 'index.html').exists() + assert (app.outdir / '_static' / 'background.png').exists() + assert not (app.outdir / '_static' / 'subdir' / '.htaccess').exists() + assert not (app.outdir / '_static' / 'subdir' / '.htpasswd').exists() + + # html_extra_path + assert (app.outdir / '.htaccess').exists() + assert not (app.outdir / '.htpasswd').exists() + assert (app.outdir / 'API.html_t').exists() + assert (app.outdir / 'css/style.css').exists() + assert (app.outdir / 'rimg.png').exists() + assert not (app.outdir / '_build' / 'index.html').exists() + assert (app.outdir / 'background.png').exists() + assert (app.outdir / 'subdir' / '.htaccess').exists() + assert not (app.outdir / 'subdir' / '.htpasswd').exists() + + # html_css_files + content = (app.outdir / 'index.html').read_text(encoding='utf8') + assert '<link rel="stylesheet" type="text/css" href="_static/css/style.css" />' in content + assert ('<link media="print" rel="stylesheet" title="title" type="text/css" ' + 'href="https://example.com/custom.css" />' in content) + + # html_js_files + assert '<script src="_static/js/custom.js"></script>' in content + assert ('<script async="async" src="https://example.com/script.js">' + '</script>' in content) + + +@pytest.mark.sphinx('html', testroot='html_assets') +def test_assets_order(app, monkeypatch): + monkeypatch.setattr(sphinx.builders.html, '_file_checksum', lambda o, f: '') + + app.add_css_file('normal.css') + app.add_css_file('early.css', priority=100) + app.add_css_file('late.css', priority=750) + app.add_css_file('lazy.css', priority=900) + app.add_js_file('normal.js') + app.add_js_file('early.js', priority=100) + app.add_js_file('late.js', priority=750) + app.add_js_file('lazy.js', priority=900) + + app.build(force_all=True) + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + # css_files + expected = [ + '_static/early.css', + '_static/pygments.css', + '_static/alabaster.css', + 'https://example.com/custom.css', + '_static/normal.css', + '_static/late.css', + '_static/css/style.css', + '_static/lazy.css', + ] + pattern = '.*'.join(f'href="{re.escape(f)}"' for f in expected) + assert re.search(pattern, content, re.DOTALL), content + + # js_files + expected = [ + '_static/early.js', + '_static/doctools.js', + '_static/sphinx_highlight.js', + 'https://example.com/script.js', + '_static/normal.js', + '_static/late.js', + '_static/js/custom.js', + '_static/lazy.js', + ] + pattern = '.*'.join(f'src="{re.escape(f)}"' for f in expected) + assert re.search(pattern, content, re.DOTALL), content + + +@pytest.mark.sphinx('html', testroot='html_file_checksum') +def test_file_checksum(app): + app.add_css_file('stylesheet-a.css') + app.add_css_file('stylesheet-b.css') + app.add_css_file('https://example.com/custom.css') + app.add_js_file('script.js') + app.add_js_file('empty.js') + app.add_js_file('https://example.com/script.js') + + app.build(force_all=True) + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + # checksum for local files + assert '<link rel="stylesheet" type="text/css" href="_static/stylesheet-a.css?v=e575b6df" />' in content + assert '<link rel="stylesheet" type="text/css" href="_static/stylesheet-b.css?v=a2d5cc0f" />' in content + assert '<script src="_static/script.js?v=48278d48"></script>' in content + + # empty files have no checksum + assert '<script src="_static/empty.js"></script>' in content + + # no checksum for hyperlinks + assert '<link rel="stylesheet" type="text/css" href="https://example.com/custom.css" />' in content + assert '<script src="https://example.com/script.js"></script>' in content + + +def test_file_checksum_query_string(): + with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'): + _file_checksum(Path(), 'with_query_string.css?dead_parrots=1') + + with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'): + _file_checksum(Path(), 'with_query_string.js?dead_parrots=1') + + with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'): + _file_checksum(Path.cwd(), '_static/with_query_string.css?dead_parrots=1') + + with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'): + _file_checksum(Path.cwd(), '_static/with_query_string.js?dead_parrots=1') + + +@pytest.mark.sphinx('html', testroot='html_assets') +def test_javscript_loading_method(app): + app.add_js_file('normal.js') + app.add_js_file('early.js', loading_method='async') + app.add_js_file('late.js', loading_method='defer') + + app.build(force_all=True) + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert '<script src="_static/normal.js"></script>' in content + assert '<script async="async" src="_static/early.js"></script>' in content + assert '<script defer="defer" src="_static/late.js"></script>' in content diff --git a/tests/test_builders/test_build_html_code.py b/tests/test_builders/test_build_html_code.py new file mode 100644 index 0000000..f07eb97 --- /dev/null +++ b/tests/test_builders/test_build_html_code.py @@ -0,0 +1,46 @@ +import pytest + + +@pytest.mark.sphinx('html', testroot='reST-code-block', + confoverrides={'html_codeblock_linenos_style': 'table'}) +def test_html_codeblock_linenos_style_table(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert ('<div class="linenodiv"><pre><span class="normal">1</span>\n' + '<span class="normal">2</span>\n' + '<span class="normal">3</span>\n' + '<span class="normal">4</span></pre></div>') in content + + +@pytest.mark.sphinx('html', testroot='reST-code-block', + confoverrides={'html_codeblock_linenos_style': 'inline'}) +def test_html_codeblock_linenos_style_inline(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + assert '<span class="linenos">1</span>' in content + + +@pytest.mark.sphinx('html', testroot='reST-code-role') +def test_html_code_role(app): + app.build() + content = (app.outdir / 'index.html').read_text(encoding='utf8') + + common_content = ( + '<span class="k">def</span> <span class="nf">foo</span>' + '<span class="p">(</span>' + '<span class="mi">1</span> ' + '<span class="o">+</span> ' + '<span class="mi">2</span> ' + '<span class="o">+</span> ' + '<span class="kc">None</span> ' + '<span class="o">+</span> ' + '<span class="s2">"abc"</span>' + '<span class="p">):</span> ' + '<span class="k">pass</span>') + assert ('<p>Inline <code class="code highlight python docutils literal highlight-python">' + + common_content + '</code> code block</p>') in content + assert ('<div class="highlight-python notranslate">' + + '<div class="highlight"><pre><span></span>' + + common_content) in content diff --git a/tests/test_builders/test_build_html_download.py b/tests/test_builders/test_build_html_download.py new file mode 100644 index 0000000..1201c66 --- /dev/null +++ b/tests/test_builders/test_build_html_download.py @@ -0,0 +1,62 @@ +import hashlib +import re + +import pytest + + +@pytest.mark.sphinx('html') +@pytest.mark.test_params(shared_result='test_build_html_output') +def test_html_download(app): + app.build() + + # subdir/includes.html + result = (app.outdir / 'subdir' / 'includes.html').read_text(encoding='utf8') + pattern = ('<a class="reference download internal" download="" ' + 'href="../(_downloads/.*/img.png)">') + matched = re.search(pattern, result) + assert matched + assert (app.outdir / matched.group(1)).exists() + filename = matched.group(1) + + # includes.html + result = (app.outdir / 'includes.html').read_text(encoding='utf8') + pattern = ('<a class="reference download internal" download="" ' + 'href="(_downloads/.*/img.png)">') + matched = re.search(pattern, result) + assert matched + assert (app.outdir / matched.group(1)).exists() + assert matched.group(1) == filename + + pattern = ('<a class="reference download internal" download="" ' + 'href="(_downloads/.*/)(file_with_special_%23_chars.xyz)">') + matched = re.search(pattern, result) + assert matched + assert (app.outdir / matched.group(1) / "file_with_special_#_chars.xyz").exists() + + +@pytest.mark.sphinx('html', testroot='roles-download') +def test_html_download_role(app, status, warning): + app.build() + digest = hashlib.md5(b'dummy.dat', usedforsecurity=False).hexdigest() + assert (app.outdir / '_downloads' / digest / 'dummy.dat').exists() + digest_another = hashlib.md5(b'another/dummy.dat', usedforsecurity=False).hexdigest() + assert (app.outdir / '_downloads' / digest_another / 'dummy.dat').exists() + + content = (app.outdir / 'index.html').read_text(encoding='utf8') + assert (('<li><p><a class="reference download internal" download="" ' + 'href="_downloads/%s/dummy.dat">' + '<code class="xref download docutils literal notranslate">' + '<span class="pre">dummy.dat</span></code></a></p></li>' % digest) + in content) + assert (('<li><p><a class="reference download internal" download="" ' + 'href="_downloads/%s/dummy.dat">' + '<code class="xref download docutils literal notranslate">' + '<span class="pre">another/dummy.dat</span></code></a></p></li>' % + digest_another) in content) + assert ('<li><p><code class="xref download docutils literal notranslate">' + '<span class="pre">not_found.dat</span></code></p></li>' in content) + assert ('<li><p><a class="reference download external" download="" ' + 'href="https://www.sphinx-doc.org/en/master/_static/sphinx-logo.svg">' + '<code class="xref download docutils literal notranslate">' + '<span class="pre">Sphinx</span> <span class="pre">logo</span>' + '</code></a></p></li>' in content) diff --git a/tests/test_builders/test_build_html_highlight.py b/tests/test_builders/test_build_html_highlight.py new file mode 100644 index 0000000..aee1ece --- /dev/null +++ b/tests/test_builders/test_build_html_highlight.py @@ -0,0 +1,61 @@ +from unittest.mock import ANY, call, patch + +import pytest + + +@pytest.mark.sphinx('html', testroot='basic') +def test_html_pygments_style_default(app): + style = app.builder.highlighter.formatter_args.get('style') + assert style.__name__ == 'Alabaster' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'pygments_style': 'sphinx'}) +def test_html_pygments_style_manually(app): + style = app.builder.highlighter.formatter_args.get('style') + assert style.__name__ == 'SphinxStyle' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'html_theme': 'classic'}) +def test_html_pygments_for_classic_theme(app): + style = app.builder.highlighter.formatter_args.get('style') + assert style.__name__ == 'SphinxStyle' + + +@pytest.mark.sphinx('html', testroot='basic') +def test_html_dark_pygments_style_default(app): + assert app.builder.dark_highlighter is None + + +@pytest.mark.sphinx('html', testroot='highlight_options') +def test_highlight_options(app): + subject = app.builder.highlighter + with patch.object(subject, 'highlight_block', wraps=subject.highlight_block) as highlight: + app.build() + + call_args = highlight.call_args_list + assert len(call_args) == 3 + assert call_args[0] == call(ANY, 'default', force=False, linenos=False, + location=ANY, opts={'default_option': True}) + assert call_args[1] == call(ANY, 'python', force=False, linenos=False, + location=ANY, opts={'python_option': True}) + assert call_args[2] == call(ANY, 'java', force=False, linenos=False, + location=ANY, opts={}) + + +@pytest.mark.sphinx('html', testroot='highlight_options', + confoverrides={'highlight_options': {'default_option': True}}) +def test_highlight_options_old(app): + subject = app.builder.highlighter + with patch.object(subject, 'highlight_block', wraps=subject.highlight_block) as highlight: + app.build() + + call_args = highlight.call_args_list + assert len(call_args) == 3 + assert call_args[0] == call(ANY, 'default', force=False, linenos=False, + location=ANY, opts={'default_option': True}) + assert call_args[1] == call(ANY, 'python', force=False, linenos=False, + location=ANY, opts={}) + assert call_args[2] == call(ANY, 'java', force=False, linenos=False, + location=ANY, opts={}) diff --git a/tests/test_builders/test_build_html_image.py b/tests/test_builders/test_build_html_image.py new file mode 100644 index 0000000..08ed618 --- /dev/null +++ b/tests/test_builders/test_build_html_image.py @@ -0,0 +1,80 @@ +import re +from pathlib import Path + +import docutils +import pytest + + +@pytest.mark.sphinx('html', testroot='images') +def test_html_remote_images(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<img alt="http://localhost:7777/sphinx.png" ' + 'src="http://localhost:7777/sphinx.png" />' in result) + assert not (app.outdir / 'sphinx.png').exists() + + +@pytest.mark.sphinx('html', testroot='image-escape') +def test_html_encoded_image(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<img alt="_images/img_%231.png" src="_images/img_%231.png" />' in result) + assert (app.outdir / '_images/img_#1.png').exists() + + +@pytest.mark.sphinx('html', testroot='remote-logo') +def test_html_remote_logo(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<img class="logo" src="https://www.python.org/static/img/python-logo.png" alt="Logo"/>' in result) + assert ('<link rel="icon" href="https://www.python.org/static/favicon.ico"/>' in result) + assert not (app.outdir / 'python-logo.png').exists() + + +@pytest.mark.sphinx('html', testroot='local-logo') +def test_html_local_logo(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'index.html').read_text(encoding='utf8') + assert ('<img class="logo" src="_static/img.png" alt="Logo"/>' in result) + assert (app.outdir / '_static/img.png').exists() + + +@pytest.mark.sphinx(testroot='html_scaled_image_link') +def test_html_scaled_image_link(app): + app.build() + context = (app.outdir / 'index.html').read_text(encoding='utf8') + + # no scaled parameters + assert re.search('\n<img alt="_images/img.png" src="_images/img.png" />', context) + + # scaled_image_link + # Docutils 0.21 adds a newline before the closing </a> tag + closing_space = "\n" if docutils.__version_info__[:2] >= (0, 21) else "" + assert re.search('\n<a class="reference internal image-reference" href="_images/img.png">' + '<img alt="_images/img.png" src="_images/img.png" style="[^"]+" />' + f'{closing_space}</a>', + context) + + # no-scaled-link class disables the feature + assert re.search('\n<img alt="_images/img.png" class="no-scaled-link"' + ' src="_images/img.png" style="[^"]+" />', + context) + + +@pytest.mark.sphinx('html', testroot='images') +def test_copy_images(app, status, warning): + app.build() + + images_dir = Path(app.outdir) / '_images' + images = {image.name for image in images_dir.rglob('*')} + assert images == { + 'img.png', + 'rimg.png', + 'rimg1.png', + 'svgimg.svg', + 'testimäge.png', + } diff --git a/tests/test_builders/test_build_html_maths.py b/tests/test_builders/test_build_html_maths.py new file mode 100644 index 0000000..900846b --- /dev/null +++ b/tests/test_builders/test_build_html_maths.py @@ -0,0 +1,58 @@ +import pytest + +from sphinx.errors import ConfigError + + +@pytest.mark.sphinx('html', testroot='basic') +def test_default_html_math_renderer(app, status, warning): + assert app.builder.math_renderer_name == 'mathjax' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinx.ext.mathjax']}) +def test_html_math_renderer_is_mathjax(app, status, warning): + assert app.builder.math_renderer_name == 'mathjax' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinx.ext.imgmath']}) +def test_html_math_renderer_is_imgmath(app, status, warning): + assert app.builder.math_renderer_name == 'imgmath' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinxcontrib.jsmath', + 'sphinx.ext.imgmath']}) +def test_html_math_renderer_is_duplicated(make_app, app_params): + args, kwargs = app_params + with pytest.raises( + ConfigError, + match='Many math_renderers are registered. But no math_renderer is selected.', + ): + make_app(*args, **kwargs) + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinx.ext.imgmath', + 'sphinx.ext.mathjax']}) +def test_html_math_renderer_is_duplicated2(app, status, warning): + # case of both mathjax and another math_renderer is loaded + assert app.builder.math_renderer_name == 'imgmath' # The another one is chosen + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinxcontrib.jsmath', + 'sphinx.ext.imgmath'], + 'html_math_renderer': 'imgmath'}) +def test_html_math_renderer_is_chosen(app, status, warning): + assert app.builder.math_renderer_name == 'imgmath' + + +@pytest.mark.sphinx('html', testroot='basic', + confoverrides={'extensions': ['sphinxcontrib.jsmath', + 'sphinx.ext.mathjax'], + 'html_math_renderer': 'imgmath'}) +def test_html_math_renderer_is_mismatched(make_app, app_params): + args, kwargs = app_params + with pytest.raises(ConfigError, match="Unknown math_renderer 'imgmath' is given."): + make_app(*args, **kwargs) diff --git a/tests/test_builders/test_build_html_numfig.py b/tests/test_builders/test_build_html_numfig.py new file mode 100644 index 0000000..62e68cb --- /dev/null +++ b/tests/test_builders/test_build_html_numfig.py @@ -0,0 +1,487 @@ +"""Test the HTML builder and check output against XPath.""" + +import os +import re + +import pytest + +from tests.test_builders.xpath_data import FIGURE_CAPTION +from tests.test_builders.xpath_util import check_xpath + + +@pytest.mark.sphinx('html', testroot='numfig') +@pytest.mark.test_params(shared_result='test_build_html_numfig') +def test_numfig_disabled_warn(app, warning): + app.build() + warnings = warning.getvalue() + assert 'index.rst:47: WARNING: numfig is disabled. :numref: is ignored.' in warnings + assert 'index.rst:56: WARNING: invalid numfig_format: invalid' not in warnings + assert 'index.rst:57: WARNING: invalid numfig_format: Fig %s %s' not in warnings + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", None, True), + ('index.html', ".//table/caption/span[@class='caption-number']", None, True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", None, True), + ('index.html', ".//li/p/code/span", '^fig1$', True), + ('index.html', ".//li/p/code/span", '^Figure%s$', True), + ('index.html', ".//li/p/code/span", '^table-1$', True), + ('index.html', ".//li/p/code/span", '^Table:%s$', True), + ('index.html', ".//li/p/code/span", '^CODE_1$', True), + ('index.html', ".//li/p/code/span", '^Code-%s$', True), + ('index.html', ".//li/p/a/span", '^Section 1$', True), + ('index.html', ".//li/p/a/span", '^Section 2.1$', True), + ('index.html', ".//li/p/code/span", '^Fig.{number}$', True), + ('index.html', ".//li/p/a/span", '^Sect.1 Foo$', True), + + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", None, True), + ('foo.html', ".//table/caption/span[@class='caption-number']", None, True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", None, True), + + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", None, True), + ('bar.html', ".//table/caption/span[@class='caption-number']", None, True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", None, True), + + ('baz.html', FIGURE_CAPTION + "/span[@class='caption-number']", None, True), + ('baz.html', ".//table/caption/span[@class='caption-number']", None, True), + ('baz.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", None, True), +]) +@pytest.mark.sphinx('html', testroot='numfig') +@pytest.mark.test_params(shared_result='test_build_html_numfig') +def test_numfig_disabled(app, cached_etree_parse, fname, path, check, be_found): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.sphinx( + 'html', testroot='numfig', + srcdir='test_numfig_without_numbered_toctree_warn', + confoverrides={'numfig': True}) +def test_numfig_without_numbered_toctree_warn(app, warning): + app.build() + # remove :numbered: option + index = (app.srcdir / 'index.rst').read_text(encoding='utf8') + index = re.sub(':numbered:.*', '', index) + (app.srcdir / 'index.rst').write_text(index, encoding='utf8') + app.build() + + warnings = warning.getvalue() + assert 'index.rst:47: WARNING: numfig is disabled. :numref: is ignored.' not in warnings + assert 'index.rst:55: WARNING: Failed to create a cross reference. Any number is not assigned: index' in warnings + assert 'index.rst:56: WARNING: invalid numfig_format: invalid' in warnings + assert 'index.rst:57: WARNING: invalid numfig_format: Fig %s %s' in warnings + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 9 $', True), + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 10 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 9 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 10 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 9 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 10 $', True), + ('index.html', ".//li/p/a/span", '^Fig. 9$', True), + ('index.html', ".//li/p/a/span", '^Figure6$', True), + ('index.html', ".//li/p/a/span", '^Table 9$', True), + ('index.html', ".//li/p/a/span", '^Table:6$', True), + ('index.html', ".//li/p/a/span", '^Listing 9$', True), + ('index.html', ".//li/p/a/span", '^Code-6$', True), + ('index.html', ".//li/p/code/span", '^foo$', True), + ('index.html', ".//li/p/code/span", '^bar_a$', True), + ('index.html', ".//li/p/a/span", '^Fig.9 should be Fig.1$', True), + ('index.html', ".//li/p/code/span", '^Sect.{number}$', True), + + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 3 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 4 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 2 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 3 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 4 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 3 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 4 $', True), + + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 5 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 7 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 8 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 5 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 7 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 8 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 5 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 7 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 8 $', True), + + ('baz.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 6 $', True), + ('baz.html', ".//table/caption/span[@class='caption-number']", + '^Table 6 $', True), + ('baz.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 6 $', True), +]) +@pytest.mark.sphinx( + 'html', testroot='numfig', + srcdir='test_numfig_without_numbered_toctree', + confoverrides={'numfig': True}) +def test_numfig_without_numbered_toctree(app, cached_etree_parse, fname, path, check, be_found): + # remove :numbered: option + index = (app.srcdir / 'index.rst').read_text(encoding='utf8') + index = re.sub(':numbered:.*', '', index) + (app.srcdir / 'index.rst').write_text(index, encoding='utf8') + + if not os.listdir(app.outdir): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.sphinx('html', testroot='numfig', confoverrides={'numfig': True}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_on') +def test_numfig_with_numbered_toctree_warn(app, warning): + app.build() + warnings = warning.getvalue() + assert 'index.rst:47: WARNING: numfig is disabled. :numref: is ignored.' not in warnings + assert 'index.rst:55: WARNING: Failed to create a cross reference. Any number is not assigned: index' in warnings + assert 'index.rst:56: WARNING: invalid numfig_format: invalid' in warnings + assert 'index.rst:57: WARNING: invalid numfig_format: Fig %s %s' in warnings + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1 $', True), + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 1 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 2 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2 $', True), + ('index.html', ".//li/p/a/span", '^Fig. 1$', True), + ('index.html', ".//li/p/a/span", '^Figure2.2$', True), + ('index.html', ".//li/p/a/span", '^Table 1$', True), + ('index.html', ".//li/p/a/span", '^Table:2.2$', True), + ('index.html', ".//li/p/a/span", '^Listing 1$', True), + ('index.html', ".//li/p/a/span", '^Code-2.2$', True), + ('index.html', ".//li/p/a/span", '^Section.1$', True), + ('index.html', ".//li/p/a/span", '^Section.2.1$', True), + ('index.html', ".//li/p/a/span", '^Fig.1 should be Fig.1$', True), + ('index.html', ".//li/p/a/span", '^Sect.1 Foo$', True), + + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.1 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.2 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.3 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.4 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.2 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.3 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.4 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.2 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.3 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.4 $', True), + + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.1 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.3 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.4 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.1 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.3 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.4 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.1 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.3 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.4 $', True), + + ('baz.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.2 $', True), + ('baz.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.2 $', True), + ('baz.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.2 $', True), +]) +@pytest.mark.sphinx('html', testroot='numfig', confoverrides={'numfig': True}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_on') +def test_numfig_with_numbered_toctree(app, cached_etree_parse, fname, path, check, be_found): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.sphinx('html', testroot='numfig', confoverrides={ + 'numfig': True, + 'numfig_format': {'figure': 'Figure:%s', + 'table': 'Tab_%s', + 'code-block': 'Code-%s', + 'section': 'SECTION-%s'}}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_format_warn') +def test_numfig_with_prefix_warn(app, warning): + app.build() + warnings = warning.getvalue() + assert 'index.rst:47: WARNING: numfig is disabled. :numref: is ignored.' not in warnings + assert 'index.rst:55: WARNING: Failed to create a cross reference. Any number is not assigned: index' in warnings + assert 'index.rst:56: WARNING: invalid numfig_format: invalid' in warnings + assert 'index.rst:57: WARNING: invalid numfig_format: Fig %s %s' in warnings + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:1 $', True), + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:2 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Tab_1 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Tab_2 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-1 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-2 $', True), + ('index.html', ".//li/p/a/span", '^Figure:1$', True), + ('index.html', ".//li/p/a/span", '^Figure2.2$', True), + ('index.html', ".//li/p/a/span", '^Tab_1$', True), + ('index.html', ".//li/p/a/span", '^Table:2.2$', True), + ('index.html', ".//li/p/a/span", '^Code-1$', True), + ('index.html', ".//li/p/a/span", '^Code-2.2$', True), + ('index.html', ".//li/p/a/span", '^SECTION-1$', True), + ('index.html', ".//li/p/a/span", '^SECTION-2.1$', True), + ('index.html', ".//li/p/a/span", '^Fig.1 should be Fig.1$', True), + ('index.html', ".//li/p/a/span", '^Sect.1 Foo$', True), + + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:1.1 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:1.2 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:1.3 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:1.4 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Tab_1.1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Tab_1.2 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Tab_1.3 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Tab_1.4 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-1.1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-1.2 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-1.3 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-1.4 $', True), + + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:2.1 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:2.3 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:2.4 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Tab_2.1 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Tab_2.3 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Tab_2.4 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-2.1 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-2.3 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-2.4 $', True), + + ('baz.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Figure:2.2 $', True), + ('baz.html', ".//table/caption/span[@class='caption-number']", + '^Tab_2.2 $', True), + ('baz.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Code-2.2 $', True), +]) +@pytest.mark.sphinx('html', testroot='numfig', + confoverrides={'numfig': True, + 'numfig_format': {'figure': 'Figure:%s', + 'table': 'Tab_%s', + 'code-block': 'Code-%s', + 'section': 'SECTION-%s'}}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_format_warn') +def test_numfig_with_prefix(app, cached_etree_parse, fname, path, check, be_found): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.sphinx('html', testroot='numfig', + confoverrides={'numfig': True, 'numfig_secnum_depth': 2}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_depth_2') +def test_numfig_with_secnum_depth_warn(app, warning): + app.build() + warnings = warning.getvalue() + assert 'index.rst:47: WARNING: numfig is disabled. :numref: is ignored.' not in warnings + assert 'index.rst:55: WARNING: Failed to create a cross reference. Any number is not assigned: index' in warnings + assert 'index.rst:56: WARNING: invalid numfig_format: invalid' in warnings + assert 'index.rst:57: WARNING: invalid numfig_format: Fig %s %s' in warnings + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1 $', True), + ('index.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 1 $', True), + ('index.html', ".//table/caption/span[@class='caption-number']", + '^Table 2 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1 $', True), + ('index.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2 $', True), + ('index.html', ".//li/p/a/span", '^Fig. 1$', True), + ('index.html', ".//li/p/a/span", '^Figure2.1.2$', True), + ('index.html', ".//li/p/a/span", '^Table 1$', True), + ('index.html', ".//li/p/a/span", '^Table:2.1.2$', True), + ('index.html', ".//li/p/a/span", '^Listing 1$', True), + ('index.html', ".//li/p/a/span", '^Code-2.1.2$', True), + ('index.html', ".//li/p/a/span", '^Section.1$', True), + ('index.html', ".//li/p/a/span", '^Section.2.1$', True), + ('index.html', ".//li/p/a/span", '^Fig.1 should be Fig.1$', True), + ('index.html', ".//li/p/a/span", '^Sect.1 Foo$', True), + + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.1 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.1.1 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.1.2 $', True), + ('foo.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.2.1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.1.1 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.1.2 $', True), + ('foo.html', ".//table/caption/span[@class='caption-number']", + '^Table 1.2.1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.1.1 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.1.2 $', True), + ('foo.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.2.1 $', True), + + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.1.1 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.1.3 $', True), + ('bar.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.2.1 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.1.1 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.1.3 $', True), + ('bar.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.2.1 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.1.1 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.1.3 $', True), + ('bar.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.2.1 $', True), + + ('baz.html', FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.1.2 $', True), + ('baz.html', ".//table/caption/span[@class='caption-number']", + '^Table 2.1.2 $', True), + ('baz.html', ".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.1.2 $', True), +]) +@pytest.mark.sphinx('html', testroot='numfig', + confoverrides={'numfig': True, + 'numfig_secnum_depth': 2}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_depth_2') +def test_numfig_with_secnum_depth(app, cached_etree_parse, fname, path, check, be_found): + app.build() + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.parametrize("expect", [ + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 1 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 2 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2 $', True), + (".//li/p/a/span", '^Fig. 1$', True), + (".//li/p/a/span", '^Figure2.2$', True), + (".//li/p/a/span", '^Table 1$', True), + (".//li/p/a/span", '^Table:2.2$', True), + (".//li/p/a/span", '^Listing 1$', True), + (".//li/p/a/span", '^Code-2.2$', True), + (".//li/p/a/span", '^Section.1$', True), + (".//li/p/a/span", '^Section.2.1$', True), + (".//li/p/a/span", '^Fig.1 should be Fig.1$', True), + (".//li/p/a/span", '^Sect.1 Foo$', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.1 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.2 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.3 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 1.4 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 1.1 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 1.2 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 1.3 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 1.4 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.1 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.2 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.3 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 1.4 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.1 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.3 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.4 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 2.1 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 2.3 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 2.4 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.1 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.3 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.4 $', True), + (FIGURE_CAPTION + "/span[@class='caption-number']", '^Fig. 2.2 $', True), + (".//table/caption/span[@class='caption-number']", + '^Table 2.2 $', True), + (".//div[@class='code-block-caption']/" + "span[@class='caption-number']", '^Listing 2.2 $', True), +]) +@pytest.mark.sphinx('singlehtml', testroot='numfig', confoverrides={'numfig': True}) +@pytest.mark.test_params(shared_result='test_build_html_numfig_on') +def test_numfig_with_singlehtml(app, cached_etree_parse, expect): + app.build() + check_xpath(cached_etree_parse(app.outdir / 'index.html'), 'index.html', *expect) diff --git a/tests/test_builders/test_build_html_tocdepth.py b/tests/test_builders/test_build_html_tocdepth.py new file mode 100644 index 0000000..4d99995 --- /dev/null +++ b/tests/test_builders/test_build_html_tocdepth.py @@ -0,0 +1,94 @@ +"""Test the HTML builder and check output against XPath.""" + +import pytest + +from tests.test_builders.xpath_util import check_xpath + + +@pytest.mark.parametrize(("fname", "path", "check", "be_found"), [ + ('index.html', ".//li[@class='toctree-l3']/a", '1.1.1. Foo A1', True), + ('index.html', ".//li[@class='toctree-l3']/a", '1.2.1. Foo B1', True), + ('index.html', ".//li[@class='toctree-l3']/a", '2.1.1. Bar A1', False), + ('index.html', ".//li[@class='toctree-l3']/a", '2.2.1. Bar B1', False), + + ('foo.html', ".//h1", 'Foo', True), + ('foo.html', ".//h2", 'Foo A', True), + ('foo.html', ".//h3", 'Foo A1', True), + ('foo.html', ".//h2", 'Foo B', True), + ('foo.html', ".//h3", 'Foo B1', True), + + ('foo.html', ".//h1//span[@class='section-number']", '1. ', True), + ('foo.html', ".//h2//span[@class='section-number']", '1.1. ', True), + ('foo.html', ".//h3//span[@class='section-number']", '1.1.1. ', True), + ('foo.html', ".//h2//span[@class='section-number']", '1.2. ', True), + ('foo.html', ".//h3//span[@class='section-number']", '1.2.1. ', True), + + ('foo.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '1.1. Foo A', True), + ('foo.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '1.1.1. Foo A1', True), + ('foo.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '1.2. Foo B', True), + ('foo.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '1.2.1. Foo B1', True), + + ('bar.html', ".//h1", 'Bar', True), + ('bar.html', ".//h2", 'Bar A', True), + ('bar.html', ".//h2", 'Bar B', True), + ('bar.html', ".//h3", 'Bar B1', True), + ('bar.html', ".//h1//span[@class='section-number']", '2. ', True), + ('bar.html', ".//h2//span[@class='section-number']", '2.1. ', True), + ('bar.html', ".//h2//span[@class='section-number']", '2.2. ', True), + ('bar.html', ".//h3//span[@class='section-number']", '2.2.1. ', True), + ('bar.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '2. Bar', True), + ('bar.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '2.1. Bar A', True), + ('bar.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '2.2. Bar B', True), + ('bar.html', ".//div[@class='sphinxsidebarwrapper']//li/a", '2.2.1. Bar B1', False), + + ('baz.html', ".//h1", 'Baz A', True), + ('baz.html', ".//h1//span[@class='section-number']", '2.1.1. ', True), +]) +@pytest.mark.sphinx('html', testroot='tocdepth') +@pytest.mark.test_params(shared_result='test_build_html_tocdepth') +def test_tocdepth(app, cached_etree_parse, fname, path, check, be_found): + app.build() + # issue #1251 + check_xpath(cached_etree_parse(app.outdir / fname), fname, path, check, be_found) + + +@pytest.mark.parametrize("expect", [ + (".//li[@class='toctree-l3']/a", '1.1.1. Foo A1', True), + (".//li[@class='toctree-l3']/a", '1.2.1. Foo B1', True), + (".//li[@class='toctree-l3']/a", '2.1.1. Bar A1', False), + (".//li[@class='toctree-l3']/a", '2.2.1. Bar B1', False), + + # index.rst + (".//h1", 'test-tocdepth', True), + + # foo.rst + (".//h2", 'Foo', True), + (".//h3", 'Foo A', True), + (".//h4", 'Foo A1', True), + (".//h3", 'Foo B', True), + (".//h4", 'Foo B1', True), + (".//h2//span[@class='section-number']", '1. ', True), + (".//h3//span[@class='section-number']", '1.1. ', True), + (".//h4//span[@class='section-number']", '1.1.1. ', True), + (".//h3//span[@class='section-number']", '1.2. ', True), + (".//h4//span[@class='section-number']", '1.2.1. ', True), + + # bar.rst + (".//h2", 'Bar', True), + (".//h3", 'Bar A', True), + (".//h3", 'Bar B', True), + (".//h4", 'Bar B1', True), + (".//h2//span[@class='section-number']", '2. ', True), + (".//h3//span[@class='section-number']", '2.1. ', True), + (".//h3//span[@class='section-number']", '2.2. ', True), + (".//h4//span[@class='section-number']", '2.2.1. ', True), + + # baz.rst + (".//h4", 'Baz A', True), + (".//h4//span[@class='section-number']", '2.1.1. ', True), +]) +@pytest.mark.sphinx('singlehtml', testroot='tocdepth') +@pytest.mark.test_params(shared_result='test_build_html_tocdepth') +def test_tocdepth_singlehtml(app, cached_etree_parse, expect): + app.build() + check_xpath(cached_etree_parse(app.outdir / 'index.html'), 'index.html', *expect) diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py new file mode 100644 index 0000000..0776c74 --- /dev/null +++ b/tests/test_builders/test_build_latex.py @@ -0,0 +1,1759 @@ +"""Test the build process with LaTeX builder with the test root.""" + +import http.server +import os +import re +import subprocess +from pathlib import Path +from shutil import copyfile +from subprocess import CalledProcessError + +import pytest + +from sphinx.builders.latex import default_latex_documents +from sphinx.config import Config +from sphinx.errors import SphinxError +from sphinx.ext.intersphinx import load_mappings, normalize_intersphinx_mapping +from sphinx.ext.intersphinx import setup as intersphinx_setup +from sphinx.util.osutil import ensuredir +from sphinx.writers.latex import LaTeXTranslator + +from tests.utils import http_server + +try: + from contextlib import chdir +except ImportError: + from sphinx.util.osutil import _chdir as chdir + +STYLEFILES = ['article.cls', 'fancyhdr.sty', 'titlesec.sty', 'amsmath.sty', + 'framed.sty', 'color.sty', 'fancyvrb.sty', + 'fncychap.sty', 'geometry.sty', 'kvoptions.sty', 'hyperref.sty', + 'booktabs.sty'] + + +# only run latex if all needed packages are there +def kpsetest(*filenames): + try: + subprocess.run(['kpsewhich', *list(filenames)], capture_output=True, check=True) + return True + except (OSError, CalledProcessError): + return False # command not found or exit with non-zero + + +# compile latex document with app.config.latex_engine +def compile_latex_document(app, filename='python.tex', docclass='manual'): + # now, try to run latex over it + try: + with chdir(app.outdir): + # name latex output-directory according to both engine and docclass + # to avoid reuse of auxiliary files by one docclass from another + latex_outputdir = app.config.latex_engine + docclass + ensuredir(latex_outputdir) + # keep a copy of latex file for this engine in case test fails + copyfile(filename, latex_outputdir + '/' + filename) + args = [app.config.latex_engine, + '--halt-on-error', + '--interaction=nonstopmode', + f'-output-directory={latex_outputdir}', + filename] + subprocess.run(args, capture_output=True, check=True) + except OSError as exc: # most likely the latex executable was not found + raise pytest.skip.Exception from exc + except CalledProcessError as exc: + print(exc.stdout.decode('utf8')) + print(exc.stderr.decode('utf8')) + msg = f'{app.config.latex_engine} exited with return code {exc.returncode}' + raise AssertionError(msg) from exc + + +def skip_if_requested(testfunc): + if 'SKIP_LATEX_BUILD' in os.environ: + msg = 'Skip LaTeX builds because SKIP_LATEX_BUILD is set' + return pytest.mark.skipif(True, reason=msg)(testfunc) + else: + return testfunc + + +def skip_if_stylefiles_notfound(testfunc): + if kpsetest(*STYLEFILES) is False: + msg = 'not running latex, the required styles do not seem to be installed' + return pytest.mark.skipif(True, reason=msg)(testfunc) + else: + return testfunc + + +class RemoteImageHandler(http.server.BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_GET(self): + content, content_type = None, None + if self.path == "/sphinx.png": + with open("tests/roots/test-local-logo/images/img.png", "rb") as f: + content = f.read() + content_type = "image/png" + + if content: + self.send_response(200, "OK") + self.send_header("Content-Length", str(len(content))) + self.send_header("Content-Type", content_type) + self.end_headers() + self.wfile.write(content) + else: + self.send_response(404, "Not Found") + self.send_header("Content-Length", "0") + self.end_headers() + + +@skip_if_requested +@skip_if_stylefiles_notfound +@pytest.mark.parametrize( + ('engine', 'docclass', 'python_maximum_signature_line_length'), + # Only running test with `python_maximum_signature_line_length` not None with last + # LaTeX engine to reduce testing time, as if this configuration does not fail with + # one engine, it's almost impossible it would fail with another. + [ + ('pdflatex', 'manual', None), + ('pdflatex', 'howto', None), + ('lualatex', 'manual', None), + ('lualatex', 'howto', None), + ('xelatex', 'manual', 1), + ('xelatex', 'howto', 1), + ], +) +@pytest.mark.sphinx('latex', freshenv=True) +def test_build_latex_doc(app, engine, docclass, python_maximum_signature_line_length): + app.config.python_maximum_signature_line_length = python_maximum_signature_line_length + app.config.intersphinx_mapping = { + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), + } + intersphinx_setup(app) + app.config.latex_engine = engine + app.config.latex_documents = [app.config.latex_documents[0][:4] + (docclass,)] + if engine == 'xelatex': + app.config.latex_table_style = ['booktabs'] + elif engine == 'lualatex': + app.config.latex_table_style = ['colorrows'] + normalize_intersphinx_mapping(app, app.config) + load_mappings(app) + app.builder.init() + LaTeXTranslator.ignore_missing_images = True + with http_server(RemoteImageHandler): + app.build(force_all=True) + + # file from latex_additional_files + assert (app.outdir / 'svgimg.svg').is_file() + + compile_latex_document(app, 'sphinxtests.tex', docclass) + + +@pytest.mark.sphinx('latex') +def test_writer(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'sphinxtests.tex').read_text(encoding='utf8') + + assert ('\\begin{sphinxfigure-in-table}\n\\centering\n\\capstart\n' + '\\noindent\\sphinxincludegraphics{{img}.png}\n' + '\\sphinxfigcaption{figure in table}\\label{\\detokenize{markup:id8}}' + '\\end{sphinxfigure-in-table}\\relax' in result) + + assert ('\\begin{wrapfigure}{r}{0pt}\n\\centering\n' + '\\noindent\\sphinxincludegraphics{{rimg}.png}\n' + '\\caption{figure with align option}\\label{\\detokenize{markup:id9}}' + '\\end{wrapfigure}\n\n' + '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result) + + assert ('\\begin{wrapfigure}{r}{0.500\\linewidth}\n\\centering\n' + '\\noindent\\sphinxincludegraphics{{rimg}.png}\n' + '\\caption{figure with align \\& figwidth option}' + '\\label{\\detokenize{markup:id10}}' + '\\end{wrapfigure}\n\n' + '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result) + + assert ('\\begin{wrapfigure}{r}{3cm}\n\\centering\n' + '\\noindent\\sphinxincludegraphics[width=3cm]{{rimg}.png}\n' + '\\caption{figure with align \\& width option}' + '\\label{\\detokenize{markup:id11}}' + '\\end{wrapfigure}\n\n' + '\\mbox{}\\par\\vskip-\\dimexpr\\baselineskip+\\parskip\\relax' in result) + + assert 'Footnotes' not in result + + assert ('\\begin{sphinxseealso}{See also:}\n\n' + '\\sphinxAtStartPar\n' + 'something, something else, something more\n' + '\\begin{description}\n' + '\\sphinxlineitem{\\sphinxhref{https://www.google.com}{Google}}\n' + '\\sphinxAtStartPar\n' + 'For everything.\n' + '\n' + '\\end{description}\n' + '\n\n\\end{sphinxseealso}\n\n' in result) + + +@pytest.mark.sphinx('latex', testroot='basic') +def test_latex_basic(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert r'\title{The basic Sphinx documentation for testing}' in result + assert r'\release{}' in result + assert r'\renewcommand{\releasename}{}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={ + 'latex_documents': [('index', 'test.tex', 'title', 'author', 'manual')], + }) +def test_latex_basic_manual(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{report}' in result + assert r'\documentclass[letterpaper,10pt,english]{sphinxmanual}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={ + 'latex_documents': [('index', 'test.tex', 'title', 'author', 'howto')], + }) +def test_latex_basic_howto(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{article}' in result + assert r'\documentclass[letterpaper,10pt,english]{sphinxhowto}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={ + 'language': 'ja', + 'latex_documents': [('index', 'test.tex', 'title', 'author', 'manual')], + }) +def test_latex_basic_manual_ja(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{ujbook}' in result + assert r'\documentclass[letterpaper,10pt,dvipdfmx]{sphinxmanual}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={ + 'language': 'ja', + 'latex_documents': [('index', 'test.tex', 'title', 'author', 'howto')], + }) +def test_latex_basic_howto_ja(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{ujreport}' in result + assert r'\documentclass[letterpaper,10pt,dvipdfmx]{sphinxhowto}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-theme') +def test_latex_theme(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{book}' in result + assert r'\documentclass[a4paper,12pt,english]{sphinxbook}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-theme', + confoverrides={'latex_elements': {'papersize': 'b5paper', + 'pointsize': '9pt'}}) +def test_latex_theme_papersize(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{book}' in result + assert r'\documentclass[b5paper,9pt,english]{sphinxbook}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-theme', + confoverrides={'latex_theme_options': {'papersize': 'b5paper', + 'pointsize': '9pt'}}) +def test_latex_theme_options(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert r'\def\sphinxdocclass{book}' in result + assert r'\documentclass[b5paper,9pt,english]{sphinxbook}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', confoverrides={'language': 'zh'}) +def test_latex_additional_settings_for_language_code(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert r'\usepackage{xeCJK}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', confoverrides={'language': 'el'}) +def test_latex_additional_settings_for_greek(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\usepackage{polyglossia}\n\\setmainlanguage{greek}' in result + assert '\\newfontfamily\\greekfonttt{FreeMono}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-title') +def test_latex_title_after_admonitions(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\title{test\\sphinxhyphen{}latex\\sphinxhyphen{}title}' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={'release': '1.0_0'}) +def test_latex_release(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert r'\release{1.0\_0}' in result + assert r'\renewcommand{\releasename}{Release}' in result + + +@pytest.mark.sphinx('latex', testroot='numfig', + confoverrides={'numfig': True}) +def test_numref(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\hyperref[\\detokenize{index:fig1}]' + '{Fig.\\@ \\ref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{baz:fig22}]' + '{Figure\\ref{\\detokenize{baz:fig22}}}') in result + assert ('\\hyperref[\\detokenize{index:table-1}]' + '{Table \\ref{\\detokenize{index:table-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:table22}]' + '{Table:\\ref{\\detokenize{baz:table22}}}') in result + assert ('\\hyperref[\\detokenize{index:code-1}]' + '{Listing \\ref{\\detokenize{index:code-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:code22}]' + '{Code\\sphinxhyphen{}\\ref{\\detokenize{baz:code22}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]' + '{Section \\ref{\\detokenize{foo:foo}}}') in result + assert ('\\hyperref[\\detokenize{bar:bar-a}]' + '{Section \\ref{\\detokenize{bar:bar-a}}}') in result + assert ('\\hyperref[\\detokenize{index:fig1}]{Fig.\\ref{\\detokenize{index:fig1}} ' + '\\nameref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]{Sect.\\ref{\\detokenize{foo:foo}} ' + '\\nameref{\\detokenize{foo:foo}}}') in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\addto\captionsenglish{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsenglish{\renewcommand{\tablename}{Table }}' in result + assert r'\addto\captionsenglish{\renewcommand{\literalblockname}{Listing}}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='numfig', + confoverrides={'numfig': True, + 'numfig_format': {'figure': 'Figure:%s', + 'table': 'Tab_%s', + 'code-block': 'Code-%s', + 'section': 'SECTION-%s'}}) +def test_numref_with_prefix1(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\ref{\\detokenize{index:fig1}}' in result + assert '\\ref{\\detokenize{baz:fig22}}' in result + assert '\\ref{\\detokenize{index:table-1}}' in result + assert '\\ref{\\detokenize{baz:table22}}' in result + assert '\\ref{\\detokenize{index:code-1}}' in result + assert '\\ref{\\detokenize{baz:code22}}' in result + assert ('\\hyperref[\\detokenize{index:fig1}]' + '{Figure:\\ref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{baz:fig22}]' + '{Figure\\ref{\\detokenize{baz:fig22}}}') in result + assert ('\\hyperref[\\detokenize{index:table-1}]' + '{Tab\\_\\ref{\\detokenize{index:table-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:table22}]' + '{Table:\\ref{\\detokenize{baz:table22}}}') in result + assert ('\\hyperref[\\detokenize{index:code-1}]' + '{Code\\sphinxhyphen{}\\ref{\\detokenize{index:code-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:code22}]' + '{Code\\sphinxhyphen{}\\ref{\\detokenize{baz:code22}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]' + '{SECTION\\sphinxhyphen{}\\ref{\\detokenize{foo:foo}}}') in result + assert ('\\hyperref[\\detokenize{bar:bar-a}]' + '{SECTION\\sphinxhyphen{}\\ref{\\detokenize{bar:bar-a}}}') in result + assert ('\\hyperref[\\detokenize{index:fig1}]{Fig.\\ref{\\detokenize{index:fig1}} ' + '\\nameref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]{Sect.\\ref{\\detokenize{foo:foo}} ' + '\\nameref{\\detokenize{foo:foo}}}') in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\addto\captionsenglish{\renewcommand{\figurename}{Figure:}}' in result + assert r'\addto\captionsenglish{\renewcommand{\tablename}{Tab\_}}' in result + assert r'\addto\captionsenglish{\renewcommand{\literalblockname}{Code-}}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='numfig', + confoverrides={'numfig': True, + 'numfig_format': {'figure': 'Figure:%s.', + 'table': 'Tab_%s:', + 'code-block': 'Code-%s | ', + 'section': 'SECTION_%s_'}}) +def test_numref_with_prefix2(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\hyperref[\\detokenize{index:fig1}]' + '{Figure:\\ref{\\detokenize{index:fig1}}.\\@}') in result + assert ('\\hyperref[\\detokenize{baz:fig22}]' + '{Figure\\ref{\\detokenize{baz:fig22}}}') in result + assert ('\\hyperref[\\detokenize{index:table-1}]' + '{Tab\\_\\ref{\\detokenize{index:table-1}}:}') in result + assert ('\\hyperref[\\detokenize{baz:table22}]' + '{Table:\\ref{\\detokenize{baz:table22}}}') in result + assert ('\\hyperref[\\detokenize{index:code-1}]{Code\\sphinxhyphen{}\\ref{\\detokenize{index:code-1}} ' + '| }') in result + assert ('\\hyperref[\\detokenize{baz:code22}]' + '{Code\\sphinxhyphen{}\\ref{\\detokenize{baz:code22}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]' + '{SECTION\\_\\ref{\\detokenize{foo:foo}}\\_}') in result + assert ('\\hyperref[\\detokenize{bar:bar-a}]' + '{SECTION\\_\\ref{\\detokenize{bar:bar-a}}\\_}') in result + assert ('\\hyperref[\\detokenize{index:fig1}]{Fig.\\ref{\\detokenize{index:fig1}} ' + '\\nameref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]{Sect.\\ref{\\detokenize{foo:foo}} ' + '\\nameref{\\detokenize{foo:foo}}}') in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\addto\captionsenglish{\renewcommand{\figurename}{Figure:}}' in result + assert r'\def\fnum@figure{\figurename\thefigure{}.}' in result + assert r'\addto\captionsenglish{\renewcommand{\tablename}{Tab\_}}' in result + assert r'\def\fnum@table{\tablename\thetable{}:}' in result + assert r'\addto\captionsenglish{\renewcommand{\literalblockname}{Code-}}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='numfig', + confoverrides={'numfig': True, 'language': 'ja'}) +def test_numref_with_language_ja(app, status, warning): + app.build() + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\hyperref[\\detokenize{index:fig1}]' + '{\u56f3 \\ref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{baz:fig22}]' + '{Figure\\ref{\\detokenize{baz:fig22}}}') in result + assert ('\\hyperref[\\detokenize{index:table-1}]' + '{\u8868 \\ref{\\detokenize{index:table-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:table22}]' + '{Table:\\ref{\\detokenize{baz:table22}}}') in result + assert ('\\hyperref[\\detokenize{index:code-1}]' + '{\u30ea\u30b9\u30c8 \\ref{\\detokenize{index:code-1}}}') in result + assert ('\\hyperref[\\detokenize{baz:code22}]' + '{Code\\sphinxhyphen{}\\ref{\\detokenize{baz:code22}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]' + '{\\ref{\\detokenize{foo:foo}} \u7ae0}') in result + assert ('\\hyperref[\\detokenize{bar:bar-a}]' + '{\\ref{\\detokenize{bar:bar-a}} \u7ae0}') in result + assert ('\\hyperref[\\detokenize{index:fig1}]{Fig.\\ref{\\detokenize{index:fig1}} ' + '\\nameref{\\detokenize{index:fig1}}}') in result + assert ('\\hyperref[\\detokenize{foo:foo}]{Sect.\\ref{\\detokenize{foo:foo}} ' + '\\nameref{\\detokenize{foo:foo}}}') in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert '\\@iden{\\renewcommand{\\figurename}{図 }}' in result + assert '\\@iden{\\renewcommand{\\tablename}{表 }}' in result + assert '\\@iden{\\renewcommand{\\literalblockname}{リスト}}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-numfig') +def test_latex_obey_numfig_is_false(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') + assert '\\usepackage{sphinx}' in result + + result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') + assert '\\usepackage{sphinx}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-numfig', + confoverrides={'numfig': True, 'numfig_secnum_depth': 0}) +def test_latex_obey_numfig_secnum_depth_is_zero(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') + assert '\\usepackage[,nonumfigreset,mathnumfig]{sphinx}' in result + + result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') + assert '\\usepackage[,nonumfigreset,mathnumfig]{sphinx}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-numfig', + confoverrides={'numfig': True, 'numfig_secnum_depth': 2}) +def test_latex_obey_numfig_secnum_depth_is_two(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') + assert '\\usepackage[,numfigreset=2,mathnumfig]{sphinx}' in result + + result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') + assert '\\usepackage[,numfigreset=3,mathnumfig]{sphinx}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-numfig', + confoverrides={'numfig': True, 'math_numfig': False}) +def test_latex_obey_numfig_but_math_numfig_false(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') + assert '\\usepackage[,numfigreset=1]{sphinx}' in result + + result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') + assert '\\usepackage[,numfigreset=2]{sphinx}' in result + + +@pytest.mark.sphinx('latex', testroot='basic') +def test_latex_add_latex_package(app, status, warning): + app.add_latex_package('foo') + app.add_latex_package('bar', 'baz') + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + assert '\\usepackage{foo}' in result + assert '\\usepackage[baz]{bar}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-babel') +def test_babel_with_no_language_settings(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,english]{sphinxmanual}' in result + assert '\\usepackage{babel}' in result + assert '\\usepackage{tgtermes}' in result + assert '\\usepackage[Bjarne]{fncychap}' in result + assert ('\\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff{"}' in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{page}' in result + assert r'\addto\captionsenglish{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsenglish{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'de'}) +def test_babel_with_language_de(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,ngerman]{sphinxmanual}' in result + assert '\\usepackage{babel}' in result + assert '\\usepackage{tgtermes}' in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsngerman{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff{"}' in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{Seite}' in result + assert r'\addto\captionsngerman{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsngerman{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'ru'}) +def test_babel_with_language_ru(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,russian]{sphinxmanual}' in result + assert '\\usepackage{babel}' in result + assert '\\usepackage{tgtermes}' not in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsrussian{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff{"}' in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{страница}' in result + assert r'\addto\captionsrussian{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsrussian{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'tr'}) +def test_babel_with_language_tr(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,turkish]{sphinxmanual}' in result + assert '\\usepackage{babel}' in result + assert '\\usepackage{tgtermes}' in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsturkish{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff{=}' in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{sayfa}' in result + assert r'\addto\captionsturkish{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsturkish{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'ja'}) +def test_babel_with_language_ja(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,dvipdfmx]{sphinxmanual}' in result + assert '\\usepackage{babel}' not in result + assert '\\usepackage{tgtermes}' in result + assert '\\usepackage[Sonny]{fncychap}' not in result + assert '\\renewcommand{\\contentsname}{Table of content}\n' in result + assert '\\shorthandoff' not in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{ページ}' in result + assert '\\@iden{\\renewcommand{\\figurename}{Fig.\\@{} }}' in result + assert '\\@iden{\\renewcommand{\\tablename}{Table.\\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'unknown'}) +def test_babel_with_unknown_language(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,english]{sphinxmanual}' in result + assert '\\usepackage{babel}' in result + assert '\\usepackage{tgtermes}' in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff' in result + + assert "WARNING: no Babel option known for language 'unknown'" in warning.getvalue() + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{page}' in result + assert r'\addto\captionsenglish{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsenglish{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'de', 'latex_engine': 'lualatex'}) +def test_polyglossia_with_language_de(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,german]{sphinxmanual}' in result + assert '\\usepackage{polyglossia}' in result + assert '\\setmainlanguage[spelling=new]{german}' in result + assert '\\usepackage{tgtermes}' not in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsgerman{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff' not in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{Seite}' in result + assert r'\addto\captionsgerman{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsgerman{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='latex-babel', + confoverrides={'language': 'de-1901', 'latex_engine': 'lualatex'}) +def test_polyglossia_with_language_de_1901(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\documentclass[letterpaper,10pt,german]{sphinxmanual}' in result + assert '\\usepackage{polyglossia}' in result + assert '\\setmainlanguage[spelling=old]{german}' in result + assert '\\usepackage{tgtermes}' not in result + assert '\\usepackage[Sonny]{fncychap}' in result + assert ('\\addto\\captionsgerman{\\renewcommand{\\contentsname}{Table of content}}\n' + in result) + assert '\\shorthandoff' not in result + + # sphinxmessages.sty + result = (app.outdir / 'sphinxmessages.sty').read_text(encoding='utf8') + print(result) + assert r'\def\pageautorefname{page}' in result + assert r'\addto\captionsgerman{\renewcommand{\figurename}{Fig.\@{} }}' in result + assert r'\addto\captionsgerman{\renewcommand{\tablename}{Table.\@{} }}' in result + + +@pytest.mark.sphinx('latex') +def test_footnote(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'sphinxtests.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\sphinxAtStartPar\n%\n\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'numbered\n%\n\\end{footnote}') in result + assert ('\\begin{footnote}[2]\\sphinxAtStartFootnote\nauto numbered\n%\n' + '\\end{footnote}') in result + assert '\\begin{footnote}[3]\\sphinxAtStartFootnote\nnamed\n%\n\\end{footnote}' in result + assert '\\sphinxcite{footnote:bar}' in result + assert ('\\bibitem[bar]{footnote:bar}\n\\sphinxAtStartPar\ncite\n') in result + assert '\\sphinxcaption{Table caption \\sphinxfootnotemark[4]' in result + assert ('\\sphinxmidrule\n\\sphinxtableatstartofbodyhook%\n' + '\\begin{footnotetext}[4]\\sphinxAtStartFootnote\n' + 'footnote in table caption\n%\n\\end{footnotetext}\\ignorespaces %\n' + '\\begin{footnotetext}[5]\\sphinxAtStartFootnote\n' + 'footnote in table header\n%\n\\end{footnotetext}\\ignorespaces ' + '\n\\sphinxAtStartPar\n' + 'VIDIOC\\_CROPCAP\n&\n\\sphinxAtStartPar\n') in result + assert ('Information about VIDIOC\\_CROPCAP %\n' + '\\begin{footnote}[6]\\sphinxAtStartFootnote\n' + 'footnote in table not in header\n%\n\\end{footnote}\n\\\\\n' + '\\sphinxbottomrule\n\\end{tabulary}\n' + '\\sphinxtableafterendhook\\par\n\\sphinxattableend\\end{savenotes}\n') in result + + +@pytest.mark.sphinx('latex', testroot='footnotes') +def test_reference_in_caption_and_codeblock_in_footnote(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\caption{This is the figure caption with a reference to ' + '\\sphinxcite{index:authoryear}.}' in result) + assert '\\chapter{The section with a reference to {[}AuthorYear{]}}' in result + assert ('\\sphinxcaption{The table title with a reference' + ' to {[}AuthorYear{]}}' in result) + assert '\\subsubsection*{The rubric title with a reference to {[}AuthorYear{]}}' in result + assert ('\\chapter{The section with a reference to \\sphinxfootnotemark[6]}\n' + '\\label{\\detokenize{index:the-section-with-a-reference-to}}' + '%\n\\begin{footnotetext}[6]\\sphinxAtStartFootnote\n' + 'Footnote in section\n%\n\\end{footnotetext}') in result + assert ('\\caption{This is the figure caption with a footnote to ' + '\\sphinxfootnotemark[8].}\\label{\\detokenize{index:id35}}\\end{figure}\n' + '%\n\\begin{footnotetext}[8]\\sphinxAtStartFootnote\n' + 'Footnote in caption\n%\n\\end{footnotetext}') in result + assert ('\\sphinxcaption{footnote \\sphinxfootnotemark[9] in ' + 'caption of normal table}\\label{\\detokenize{index:id36}}') in result + assert ('\\caption{footnote \\sphinxfootnotemark[10] ' + 'in caption \\sphinxfootnotemark[11] of longtable\\strut}') in result + assert ('\\endlastfoot\n\\sphinxtableatstartofbodyhook\n%\n' + '\\begin{footnotetext}[10]\\sphinxAtStartFootnote\n' + 'Foot note in longtable\n%\n\\end{footnotetext}\\ignorespaces %\n' + '\\begin{footnotetext}[11]\\sphinxAtStartFootnote\n' + 'Second footnote in caption of longtable\n') in result + assert ('This is a reference to the code\\sphinxhyphen{}block in the footnote:\n' + '{\\hyperref[\\detokenize{index:codeblockinfootnote}]' + '{\\sphinxcrossref{\\DUrole{std,std-ref}{I am in a footnote}}}}') in result + assert ('&\n\\sphinxAtStartPar\nThis is one more footnote with some code in it %\n' + '\\begin{footnote}[12]\\sphinxAtStartFootnote\n' + 'Third footnote in longtable\n') in result + assert ('\\end{sphinxVerbatim}\n%\n\\end{footnote}.\n') in result + assert '\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]' in result + + +@pytest.mark.sphinx('latex', testroot='footnotes') +def test_footnote_referred_multiple_times(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + + assert ('Explicitly numbered footnote: %\n' + '\\begin{footnote}[100]' + '\\sphinxAtStartFootnote\nNumbered footnote\n%\n' + '\\end{footnote} \\sphinxfootnotemark[100]\n' + in result) + assert ('Named footnote: %\n' + '\\begin{footnote}[13]' + '\\sphinxAtStartFootnote\nNamed footnote\n%\n' + '\\end{footnote} \\sphinxfootnotemark[13]\n' + in result) + + +@pytest.mark.sphinx( + 'latex', testroot='footnotes', + confoverrides={'latex_show_urls': 'inline'}) +def test_latex_show_urls_is_inline(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('Same footnote number %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'footnote in bar\n%\n\\end{footnote} in bar.rst') in result + assert ('Auto footnote number %\n\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'footnote in baz\n%\n\\end{footnote} in baz.rst') in result + assert ('\\phantomsection\\label{\\detokenize{index:id38}}' + '{\\hyperref[\\detokenize{index:the-section' + '-with-a-reference-to-authoryear}]' + '{\\sphinxcrossref{The section with a reference to ' + '\\sphinxcite{index:authoryear}}}}') in result + assert ('\\phantomsection\\label{\\detokenize{index:id39}}' + '{\\hyperref[\\detokenize{index:the-section-with-a-reference-to}]' + '{\\sphinxcrossref{The section with a reference to }}}' in result) + assert ('First footnote: %\n\\begin{footnote}[2]\\sphinxAtStartFootnote\n' + 'First\n%\n\\end{footnote}') in result + assert ('Second footnote: %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'Second\n%\n\\end{footnote}\n') in result + assert '\\sphinxhref{https://sphinx-doc.org/}{Sphinx} (https://sphinx\\sphinxhyphen{}doc.org/)' in result + assert ('Third footnote: %\n\\begin{footnote}[3]\\sphinxAtStartFootnote\n' + 'Third \\sphinxfootnotemark[4]\n%\n\\end{footnote}%\n' + '\\begin{footnotetext}[4]\\sphinxAtStartFootnote\n' + 'Footnote inside footnote\n%\n\\end{footnotetext}\\ignorespaces') in result + assert ('Fourth footnote: %\n\\begin{footnote}[5]\\sphinxAtStartFootnote\n' + 'Fourth\n%\n\\end{footnote}\n') in result + assert ('\\sphinxhref{https://sphinx-doc.org/~test/}{URL including tilde} ' + '(https://sphinx\\sphinxhyphen{}doc.org/\\textasciitilde{}test/)') in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{URL in term} ' + '(https://sphinx\\sphinxhyphen{}doc.org/)}\n' + '\\sphinxAtStartPar\nDescription' in result) + assert ('\\sphinxlineitem{Footnote in term \\sphinxfootnotemark[7]}%\n' + '\\begin{footnotetext}[7]\\sphinxAtStartFootnote\n' in result) + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{URL in term} ' + '(https://sphinx\\sphinxhyphen{}doc.org/)}\n' + '\\sphinxAtStartPar\nDescription' in result) + assert ('\\sphinxlineitem{Footnote in term \\sphinxfootnotemark[7]}%\n' + '\\begin{footnotetext}[7]\\sphinxAtStartFootnote\n' + 'Footnote in term\n%\n\\end{footnotetext}\\ignorespaces ' + '\n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{Term in deflist} ' + '(https://sphinx\\sphinxhyphen{}doc.org/)}' + '\n\\sphinxAtStartPar\nDescription') in result + assert '\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result + assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}' + '{sphinx\\sphinxhyphen{}dev@googlegroups.com}') in result + assert '\\begin{savenotes}\\begin{fulllineitems}' not in result + + +@pytest.mark.sphinx( + 'latex', testroot='footnotes', + confoverrides={'latex_show_urls': 'footnote'}) +def test_latex_show_urls_is_footnote(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('Same footnote number %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'footnote in bar\n%\n\\end{footnote} in bar.rst') in result + assert ('Auto footnote number %\n\\begin{footnote}[2]\\sphinxAtStartFootnote\n' + 'footnote in baz\n%\n\\end{footnote} in baz.rst') in result + assert ('\\phantomsection\\label{\\detokenize{index:id38}}' + '{\\hyperref[\\detokenize{index:the-section-with-a-reference-to-authoryear}]' + '{\\sphinxcrossref{The section with a reference ' + 'to \\sphinxcite{index:authoryear}}}}') in result + assert ('\\phantomsection\\label{\\detokenize{index:id39}}' + '{\\hyperref[\\detokenize{index:the-section-with-a-reference-to}]' + '{\\sphinxcrossref{The section with a reference to }}}') in result + assert ('First footnote: %\n\\begin{footnote}[3]\\sphinxAtStartFootnote\n' + 'First\n%\n\\end{footnote}') in result + assert ('Second footnote: %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'Second\n%\n\\end{footnote}') in result + assert ('\\sphinxhref{https://sphinx-doc.org/}{Sphinx}' + '%\n\\begin{footnote}[4]\\sphinxAtStartFootnote\n' + '\\sphinxnolinkurl{https://sphinx-doc.org/}\n%\n\\end{footnote}') in result + assert ('Third footnote: %\n\\begin{footnote}[6]\\sphinxAtStartFootnote\n' + 'Third \\sphinxfootnotemark[7]\n%\n\\end{footnote}%\n' + '\\begin{footnotetext}[7]\\sphinxAtStartFootnote\n' + 'Footnote inside footnote\n%\n' + '\\end{footnotetext}\\ignorespaces') in result + assert ('Fourth footnote: %\n\\begin{footnote}[8]\\sphinxAtStartFootnote\n' + 'Fourth\n%\n\\end{footnote}\n') in result + assert ('\\sphinxhref{https://sphinx-doc.org/~test/}{URL including tilde}' + '%\n\\begin{footnote}[5]\\sphinxAtStartFootnote\n' + '\\sphinxnolinkurl{https://sphinx-doc.org/~test/}\n%\n\\end{footnote}') in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}' + '{URL in term}\\sphinxfootnotemark[10]}%\n' + '\\begin{footnotetext}[10]' + '\\sphinxAtStartFootnote\n' + '\\sphinxnolinkurl{https://sphinx-doc.org/}\n%\n' + '\\end{footnotetext}\\ignorespaces \n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxlineitem{Footnote in term \\sphinxfootnotemark[12]}%\n' + '\\begin{footnotetext}[12]' + '\\sphinxAtStartFootnote\n' + 'Footnote in term\n%\n\\end{footnotetext}\\ignorespaces ' + '\n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{Term in deflist}' + '\\sphinxfootnotemark[11]}%\n' + '\\begin{footnotetext}[11]' + '\\sphinxAtStartFootnote\n' + '\\sphinxnolinkurl{https://sphinx-doc.org/}\n%\n' + '\\end{footnotetext}\\ignorespaces \n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result) + assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}' + '{sphinx\\sphinxhyphen{}dev@googlegroups.com}\n') in result + assert '\\begin{savenotes}\\begin{fulllineitems}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='footnotes', + confoverrides={'latex_show_urls': 'no'}) +def test_latex_show_urls_is_no(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('Same footnote number %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'footnote in bar\n%\n\\end{footnote} in bar.rst') in result + assert ('Auto footnote number %\n\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'footnote in baz\n%\n\\end{footnote} in baz.rst') in result + assert ('\\phantomsection\\label{\\detokenize{index:id38}}' + '{\\hyperref[\\detokenize{index:the-section-with-a-reference-to-authoryear}]' + '{\\sphinxcrossref{The section with a reference ' + 'to \\sphinxcite{index:authoryear}}}}') in result + assert ('\\phantomsection\\label{\\detokenize{index:id39}}' + '{\\hyperref[\\detokenize{index:the-section-with-a-reference-to}]' + '{\\sphinxcrossref{The section with a reference to }}}' in result) + assert ('First footnote: %\n\\begin{footnote}[2]\\sphinxAtStartFootnote\n' + 'First\n%\n\\end{footnote}') in result + assert ('Second footnote: %\n' + '\\begin{footnote}[1]\\sphinxAtStartFootnote\n' + 'Second\n%\n\\end{footnote}') in result + assert '\\sphinxhref{https://sphinx-doc.org/}{Sphinx}' in result + assert ('Third footnote: %\n\\begin{footnote}[3]\\sphinxAtStartFootnote\n' + 'Third \\sphinxfootnotemark[4]\n%\n\\end{footnote}%\n' + '\\begin{footnotetext}[4]\\sphinxAtStartFootnote\n' + 'Footnote inside footnote\n%\n\\end{footnotetext}\\ignorespaces') in result + assert ('Fourth footnote: %\n\\begin{footnote}[5]\\sphinxAtStartFootnote\n' + 'Fourth\n%\n\\end{footnote}\n') in result + assert '\\sphinxhref{https://sphinx-doc.org/~test/}{URL including tilde}' in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{URL in term}}\n' + '\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxlineitem{Footnote in term \\sphinxfootnotemark[7]}%\n' + '\\begin{footnotetext}[7]\\sphinxAtStartFootnote\n' + 'Footnote in term\n%\n\\end{footnotetext}\\ignorespaces ' + '\n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxlineitem{\\sphinxhref{https://sphinx-doc.org/}{Term in deflist}}' + '\n\\sphinxAtStartPar\nDescription') in result + assert ('\\sphinxurl{https://github.com/sphinx-doc/sphinx}\n' in result) + assert ('\\sphinxhref{mailto:sphinx-dev@googlegroups.com}' + '{sphinx\\sphinxhyphen{}dev@googlegroups.com}\n') in result + assert '\\begin{savenotes}\\begin{fulllineitems}' not in result + + +@pytest.mark.sphinx( + 'latex', testroot='footnotes', + confoverrides={'latex_show_urls': 'footnote', + 'rst_prolog': '.. |URL| replace:: `text <https://www.example.com/>`__'}) +def test_latex_show_urls_footnote_and_substitutions(app, status, warning): + # hyperlinks in substitutions should not effect to make footnotes (refs: #4784) + test_latex_show_urls_is_footnote(app, status, warning) + + +@pytest.mark.sphinx('latex', testroot='image-in-section') +def test_image_in_section(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert ('\\chapter[Test section]{\\lowercase{\\sphinxincludegraphics' + '[width=15bp,height=15bp]}{{pic}.png} Test section}' + in result) + assert ('\\chapter[Other {[}blah{]} section]{Other {[}blah{]} ' + '\\lowercase{\\sphinxincludegraphics[width=15bp,height=15bp]}' + '{{pic}.png} section}' in result) + assert ('\\chapter{Another section}' in result) + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={'latex_logo': 'notfound.jpg'}) +def test_latex_logo_if_not_found(app, status, warning): + with pytest.raises(SphinxError): + app.build(force_all=True) + + +@pytest.mark.sphinx('latex', testroot='toctree-maxdepth') +def test_toctree_maxdepth_manual(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\setcounter{tocdepth}{1}' in result + assert '\\setcounter{secnumdepth}' not in result + assert '\\chapter{Foo}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_documents': [ + ('index', 'python.tex', 'Sphinx Tests Documentation', + 'Georg Brandl', 'howto'), + ]}) +def test_toctree_maxdepth_howto(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\setcounter{tocdepth}{2}' in result + assert '\\setcounter{secnumdepth}' not in result + assert '\\section{Foo}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'root_doc': 'foo'}) +def test_toctree_not_found(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\setcounter{tocdepth}' not in result + assert '\\setcounter{secnumdepth}' not in result + assert '\\chapter{Foo A}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'root_doc': 'bar'}) +def test_toctree_without_maxdepth(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\setcounter{tocdepth}' not in result + assert '\\setcounter{secnumdepth}' not in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'root_doc': 'qux'}) +def test_toctree_with_deeper_maxdepth(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\setcounter{tocdepth}{3}' in result + assert '\\setcounter{secnumdepth}{3}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': None}) +def test_latex_toplevel_sectioning_is_None(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\chapter{Foo}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': 'part'}) +def test_latex_toplevel_sectioning_is_part(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\part{Foo}' in result + assert '\\chapter{Foo A}' in result + assert '\\chapter{Foo B}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': 'part', + 'latex_documents': [ + ('index', 'python.tex', 'Sphinx Tests Documentation', + 'Georg Brandl', 'howto'), + ]}) +def test_latex_toplevel_sectioning_is_part_with_howto(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\part{Foo}' in result + assert '\\section{Foo A}' in result + assert '\\section{Foo B}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': 'chapter'}) +def test_latex_toplevel_sectioning_is_chapter(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\chapter{Foo}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': 'chapter', + 'latex_documents': [ + ('index', 'python.tex', 'Sphinx Tests Documentation', + 'Georg Brandl', 'howto'), + ]}) +def test_latex_toplevel_sectioning_is_chapter_with_howto(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\section{Foo}' in result + + +@pytest.mark.sphinx( + 'latex', testroot='toctree-maxdepth', + confoverrides={'latex_toplevel_sectioning': 'section'}) +def test_latex_toplevel_sectioning_is_section(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + assert '\\section{Foo}' in result + + +@skip_if_stylefiles_notfound +@pytest.mark.sphinx('latex', testroot='maxlistdepth') +def test_maxlistdepth_at_ten(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + print(status.getvalue()) + print(warning.getvalue()) + compile_latex_document(app, 'python.tex') + + +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) +@pytest.mark.test_params(shared_result='latex-table') +def test_latex_table_tabulars(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + tables = {} + for chap in re.split(r'\\(?:section|chapter){', result)[1:]: + sectname, content = chap.split('}', 1) + content = re.sub(r'\\sphinxstepscope', '', content) # filter a separator + tables[sectname] = content.strip() + + def get_expected(name): + return (app.srcdir / 'expects' / (name + '.tex')).read_text(encoding='utf8').strip() + + # simple_table + actual = tables['simple table'] + expected = get_expected('simple_table') + assert actual == expected + + # table having :widths: option + actual = tables['table having :widths: option'] + expected = get_expected('table_having_widths') + assert actual == expected + + # table having :align: option (tabulary) + actual = tables['table having :align: option (tabulary)'] + expected = get_expected('tabulary_having_widths') + assert actual == expected + + # table having :align: option (tabular) + actual = tables['table having :align: option (tabular)'] + expected = get_expected('tabular_having_widths') + assert actual == expected + + # table with tabularcolumn + actual = tables['table with tabularcolumn'] + expected = get_expected('tabularcolumn') + assert actual == expected + + # table with cell in first column having three paragraphs + actual = tables['table with cell in first column having three paragraphs'] + expected = get_expected('table_having_threeparagraphs_cell_in_first_col') + assert actual == expected + + # table having caption + actual = tables['table having caption'] + expected = get_expected('table_having_caption') + assert actual == expected + + # table having verbatim + actual = tables['table having verbatim'] + expected = get_expected('table_having_verbatim') + assert actual == expected + + # table having problematic cell + actual = tables['table having problematic cell'] + expected = get_expected('table_having_problematic_cell') + assert actual == expected + + # table having both :widths: and problematic cell + actual = tables['table having both :widths: and problematic cell'] + expected = get_expected('table_having_widths_and_problematic_cell') + assert actual == expected + + # table having both stub columns and problematic cell + actual = tables['table having both stub columns and problematic cell'] + expected = get_expected('table_having_stub_columns_and_problematic_cell') + assert actual == expected + + +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) +@pytest.mark.test_params(shared_result='latex-table') +def test_latex_table_longtable(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + tables = {} + for chap in re.split(r'\\(?:section|chapter){', result)[1:]: + sectname, content = chap.split('}', 1) + content = re.sub(r'\\sphinxstepscope', '', content) # filter a separator + tables[sectname] = content.strip() + + def get_expected(name): + return (app.srcdir / 'expects' / (name + '.tex')).read_text(encoding='utf8').strip() + + # longtable + actual = tables['longtable'] + expected = get_expected('longtable') + assert actual == expected + + # longtable having :widths: option + actual = tables['longtable having :widths: option'] + expected = get_expected('longtable_having_widths') + assert actual == expected + + # longtable having :align: option + actual = tables['longtable having :align: option'] + expected = get_expected('longtable_having_align') + assert actual == expected + + # longtable with tabularcolumn + actual = tables['longtable with tabularcolumn'] + expected = get_expected('longtable_with_tabularcolumn') + assert actual == expected + + # longtable having caption + actual = tables['longtable having caption'] + expected = get_expected('longtable_having_caption') + assert actual == expected + + # longtable having verbatim + actual = tables['longtable having verbatim'] + expected = get_expected('longtable_having_verbatim') + assert actual == expected + + # longtable having problematic cell + actual = tables['longtable having problematic cell'] + expected = get_expected('longtable_having_problematic_cell') + assert actual == expected + + # longtable having both :widths: and problematic cell + actual = tables['longtable having both :widths: and problematic cell'] + expected = get_expected('longtable_having_widths_and_problematic_cell') + assert actual == expected + + # longtable having both stub columns and problematic cell + actual = tables['longtable having both stub columns and problematic cell'] + expected = get_expected('longtable_having_stub_columns_and_problematic_cell') + assert actual == expected + + +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) +@pytest.mark.test_params(shared_result='latex-table') +def test_latex_table_complex_tables(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + tables = {} + for chap in re.split(r'\\(?:section|renewcommand){', result)[1:]: + sectname, content = chap.split('}', 1) + tables[sectname] = content.strip() + + def get_expected(name): + return (app.srcdir / 'expects' / (name + '.tex')).read_text(encoding='utf8').strip() + + # grid table + actual = tables['grid table'] + expected = get_expected('gridtable') + assert actual == expected + + # grid table with tabularcolumns + # MEMO: filename should end with tabularcolumns but tabularcolumn has been + # used in existing other cases + actual = tables['grid table with tabularcolumns having no vline'] + expected = get_expected('gridtable_with_tabularcolumn') + assert actual == expected + + # complex spanning cell + actual = tables['complex spanning cell'] + expected = get_expected('complex_spanning_cell') + assert actual == expected + + +@pytest.mark.sphinx('latex', testroot='latex-table') +def test_latex_table_with_booktabs_and_colorrows(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert r'\PassOptionsToPackage{booktabs}{sphinx}' in result + assert r'\PassOptionsToPackage{colorrows}{sphinx}' in result + # tabularcolumns + assert r'\begin{longtable}{|c|c|}' in result + # class: standard + assert r'\begin{tabulary}{\linewidth}[t]{|T|T|T|T|T|}' in result + assert r'\begin{longtable}{ll}' in result + assert r'\begin{tabular}[t]{*{2}{\X{1}{2}}}' in result + assert r'\begin{tabular}[t]{\X{30}{100}\X{70}{100}}' in result + + +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'templates_path': ['_mytemplates/latex']}) +def test_latex_table_custom_template_caseA(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert 'SALUT LES COPAINS' in result + + +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'templates_path': ['_mytemplates']}) +def test_latex_table_custom_template_caseB(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert 'SALUT LES COPAINS' not in result + + +@pytest.mark.sphinx('latex', testroot='latex-table') +@pytest.mark.test_params(shared_result='latex-table') +def test_latex_table_custom_template_caseC(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert 'SALUT LES COPAINS' not in result + + +@pytest.mark.sphinx('latex', testroot='directives-raw') +def test_latex_raw_directive(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + + # standard case + assert 'standalone raw directive (HTML)' not in result + assert ('\\label{\\detokenize{index:id1}}\n' + 'standalone raw directive (LaTeX)' in result) + + # with substitution + assert 'HTML: abc ghi' in result + assert 'LaTeX: abc def ghi' in result + + +@pytest.mark.sphinx('latex', testroot='images') +def test_latex_images(app, status, warning): + with http_server(RemoteImageHandler, port=7777): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + + # images are copied + assert '\\sphinxincludegraphics{{sphinx}.png}' in result + assert (app.outdir / 'sphinx.png').exists() + + # not found images + assert '\\sphinxincludegraphics{{NOT_EXIST}.PNG}' not in result + assert ('WARNING: Could not fetch remote image: ' + 'http://localhost:7777/NOT_EXIST.PNG [404]' in warning.getvalue()) + + # an image having target + assert ('\\sphinxhref{https://www.sphinx-doc.org/}' + '{\\sphinxincludegraphics{{rimg}.png}}\n\n' in result) + + # a centerized image having target + assert ('\\sphinxhref{https://www.python.org/}{{\\hspace*{\\fill}' + '\\sphinxincludegraphics{{rimg}.png}\\hspace*{\\fill}}}\n\n' in result) + + +@pytest.mark.sphinx('latex', testroot='latex-index') +def test_latex_index(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert ('A \\index{famous@\\spxentry{famous}}famous ' + '\\index{equation@\\spxentry{equation}}equation:\n' in result) + assert ('\n\\index{Einstein@\\spxentry{Einstein}}' + '\\index{relativity@\\spxentry{relativity}}' + '\\ignorespaces \n\\sphinxAtStartPar\nand') in result + assert ('\n\\index{main \\sphinxleftcurlybrace{}@\\spxentry{' + 'main \\sphinxleftcurlybrace{}}}\\ignorespaces ' in result) + + +@pytest.mark.sphinx('latex', testroot='latex-equations') +def test_latex_equations(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + expected = (app.srcdir / 'expects' / 'latex-equations.tex').read_text(encoding='utf8').strip() + + assert expected in result + + +@pytest.mark.sphinx('latex', testroot='image-in-parsed-literal') +def test_latex_image_in_parsed_literal(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert ('{\\sphinxunactivateextrasandspace \\raisebox{-0.5\\height}' + '{\\sphinxincludegraphics[height=2.00000cm]{{pic}.png}}' + '}AFTER') in result + + +@pytest.mark.sphinx('latex', testroot='nested-enumerated-list') +def test_latex_nested_enumerated_list(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert ('\\sphinxsetlistlabels{\\arabic}{enumi}{enumii}{}{.}%\n' + '\\setcounter{enumi}{4}\n' in result) + assert ('\\sphinxsetlistlabels{\\alph}{enumii}{enumiii}{}{.}%\n' + '\\setcounter{enumii}{3}\n' in result) + assert ('\\sphinxsetlistlabels{\\arabic}{enumiii}{enumiv}{}{)}%\n' + '\\setcounter{enumiii}{9}\n' in result) + assert ('\\sphinxsetlistlabels{\\arabic}{enumiv}{enumv}{(}{)}%\n' + '\\setcounter{enumiv}{23}\n' in result) + assert ('\\sphinxsetlistlabels{\\roman}{enumii}{enumiii}{}{.}%\n' + '\\setcounter{enumii}{2}\n' in result) + + +@pytest.mark.sphinx('latex', testroot='footnotes') +def test_latex_thebibliography(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert ('\\begin{sphinxthebibliography}{AuthorYe}\n' + '\\bibitem[AuthorYear]{index:authoryear}\n\\sphinxAtStartPar\n' + 'Author, Title, Year\n' + '\\end{sphinxthebibliography}\n' in result) + assert '\\sphinxcite{index:authoryear}' in result + + +@pytest.mark.sphinx('latex', testroot='glossary') +def test_latex_glossary(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert (r'\sphinxlineitem{ähnlich\index{ähnlich@\spxentry{ähnlich}|spxpagem}' + r'\phantomsection' + r'\label{\detokenize{index:term-ahnlich}}}' in result) + assert (r'\sphinxlineitem{boson\index{boson@\spxentry{boson}|spxpagem}\phantomsection' + r'\label{\detokenize{index:term-boson}}}' in result) + assert (r'\sphinxlineitem{\sphinxstyleemphasis{fermion}' + r'\index{fermion@\spxentry{fermion}|spxpagem}' + r'\phantomsection' + r'\label{\detokenize{index:term-fermion}}}' in result) + assert (r'\sphinxlineitem{tauon\index{tauon@\spxentry{tauon}|spxpagem}\phantomsection' + r'\label{\detokenize{index:term-tauon}}}' + r'\sphinxlineitem{myon\index{myon@\spxentry{myon}|spxpagem}\phantomsection' + r'\label{\detokenize{index:term-myon}}}' + r'\sphinxlineitem{electron\index{electron@\spxentry{electron}|spxpagem}\phantomsection' + r'\label{\detokenize{index:term-electron}}}' in result) + assert (r'\sphinxlineitem{über\index{über@\spxentry{über}|spxpagem}\phantomsection' + r'\label{\detokenize{index:term-uber}}}' in result) + + +@pytest.mark.sphinx('latex', testroot='latex-labels') +def test_latex_labels(app, status, warning): + app.build(force_all=True) + + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + + # figures + assert (r'\caption{labeled figure}' + r'\label{\detokenize{index:id1}}' + r'\label{\detokenize{index:figure2}}' + r'\label{\detokenize{index:figure1}}' + r'\end{figure}' in result) + assert (r'\caption{labeled figure}' + '\\label{\\detokenize{index:figure3}}\n' + '\\begin{sphinxlegend}\n\\sphinxAtStartPar\n' + 'with a legend\n\\end{sphinxlegend}\n' + r'\end{figure}' in result) + + # code-blocks + assert (r'\def\sphinxLiteralBlockLabel{' + r'\label{\detokenize{index:codeblock2}}' + r'\label{\detokenize{index:codeblock1}}}' in result) + assert (r'\def\sphinxLiteralBlockLabel{' + r'\label{\detokenize{index:codeblock3}}}' in result) + + # tables + assert (r'\sphinxcaption{table caption}' + r'\label{\detokenize{index:id2}}' + r'\label{\detokenize{index:table2}}' + r'\label{\detokenize{index:table1}}' in result) + assert (r'\sphinxcaption{table caption}' + r'\label{\detokenize{index:table3}}' in result) + + # sections + assert ('\\chapter{subsection}\n' + r'\label{\detokenize{index:subsection}}' + r'\label{\detokenize{index:section2}}' + r'\label{\detokenize{index:section1}}' in result) + assert ('\\section{subsubsection}\n' + r'\label{\detokenize{index:subsubsection}}' + r'\label{\detokenize{index:section3}}' in result) + assert ('\\subsection{otherdoc}\n' + r'\label{\detokenize{otherdoc:otherdoc}}' + r'\label{\detokenize{otherdoc::doc}}' in result) + + # Embedded standalone hyperlink reference (refs: #5948) + assert result.count(r'\label{\detokenize{index:section1}}') == 1 + + +@pytest.mark.sphinx('latex', testroot='latex-figure-in-admonition') +def test_latex_figure_in_admonition(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert r'\begin{figure}[H]' in result + + +def test_default_latex_documents(): + from sphinx.util import texescape + texescape.init() + config = Config({'root_doc': 'index', + 'project': 'STASI™ Documentation', + 'author': "Wolfgang Schäuble & G'Beckstein."}) + config.add('latex_engine', None, True, None) + config.add('latex_theme', 'manual', True, None) + expected = [('index', 'stasi.tex', 'STASI™ Documentation', + r"Wolfgang Schäuble \& G\textquotesingle{}Beckstein.\@{}", 'manual')] + assert default_latex_documents(config) == expected + + +@skip_if_requested +@skip_if_stylefiles_notfound +@pytest.mark.sphinx('latex', testroot='latex-includegraphics') +def test_includegraphics_oversized(app, status, warning): + app.build(force_all=True) + print(status.getvalue()) + print(warning.getvalue()) + compile_latex_document(app) + + +@pytest.mark.sphinx('latex', testroot='index_on_title') +def test_index_on_title(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert ('\\chapter{Test for index in top level title}\n' + '\\label{\\detokenize{contents:test-for-index-in-top-level-title}}' + '\\index{index@\\spxentry{index}}\n' + in result) + + +@pytest.mark.sphinx('latex', testroot='latex-unicode', + confoverrides={'latex_engine': 'pdflatex'}) +def test_texescape_for_non_unicode_supported_engine(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert 'script small e: e' in result + assert 'double struck italic small i: i' in result + assert r'superscript: \(\sp{\text{0}}\), \(\sp{\text{1}}\)' in result + assert r'subscript: \(\sb{\text{0}}\), \(\sb{\text{1}}\)' in result + + +@pytest.mark.sphinx('latex', testroot='latex-unicode', + confoverrides={'latex_engine': 'xelatex'}) +def test_texescape_for_unicode_supported_engine(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + print(result) + assert 'script small e: e' in result + assert 'double struck italic small i: i' in result + assert 'superscript: ⁰, ¹' in result + assert 'subscript: ₀, ₁' in result + + +@pytest.mark.sphinx('latex', testroot='basic', + confoverrides={'latex_elements': {'extrapackages': r'\usepackage{foo}'}}) +def test_latex_elements_extrapackages(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'test.tex').read_text(encoding='utf8') + assert r'\usepackage{foo}' in result + + +@pytest.mark.sphinx('latex', testroot='nested-tables') +def test_latex_nested_tables(app, status, warning): + app.build(force_all=True) + assert warning.getvalue() == '' + + +@pytest.mark.sphinx('latex', testroot='latex-container') +def test_latex_container(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + assert r'\begin{sphinxuseclass}{classname}' in result + assert r'\end{sphinxuseclass}' in result + + +@pytest.mark.sphinx('latex', testroot='reST-code-role') +def test_latex_code_role(app): + app.build() + content = (app.outdir / 'python.tex').read_text(encoding='utf8') + + common_content = ( + r'\PYG{k}{def} ' + r'\PYG{n+nf}{foo}' + r'\PYG{p}{(}' + r'\PYG{l+m+mi}{1} ' + r'\PYG{o}{+} ' + r'\PYG{l+m+mi}{2} ' + r'\PYG{o}{+} ' + r'\PYG{k+kc}{None} ' + r'\PYG{o}{+} ' + r'\PYG{l+s+s2}{\PYGZdq{}}' + r'\PYG{l+s+s2}{abc}' + r'\PYG{l+s+s2}{\PYGZdq{}}' + r'\PYG{p}{)}' + r'\PYG{p}{:} ' + r'\PYG{k}{pass}') + assert (r'Inline \sphinxcode{\sphinxupquote{%' + '\n' + + common_content + '%\n}} code block') in content + assert (r'\begin{sphinxVerbatim}[commandchars=\\\{\}]' + + '\n' + common_content + '\n' + r'\end{sphinxVerbatim}') in content + + +@pytest.mark.sphinx('latex', testroot='images') +def test_copy_images(app, status, warning): + app.build() + + test_dir = Path(app.outdir) + images = { + image.name for image in test_dir.rglob('*') + if image.suffix in {'.gif', '.pdf', '.png', '.svg'} + } + images.discard('sphinx.png') + assert images == { + 'img.pdf', + 'rimg.png', + 'testimäge.png', + } + + +@pytest.mark.sphinx('latex', testroot='latex-labels-before-module') +def test_duplicated_labels_before_module(app, status, warning): + app.build() + content: str = (app.outdir / 'python.tex').read_text(encoding='utf8') + + def count_label(name): + text = r'\phantomsection\label{\detokenize{%s}}' % name + return content.count(text) + + pattern = r'\\phantomsection\\label\{\\detokenize\{index:label-(?:auto-)?\d+[a-z]*}}' + # labels found in the TeX output + output_labels = frozenset(match.group() for match in re.finditer(pattern, content)) + # labels that have been tested and occurring exactly once in the output + tested_labels = set() + + # iterate over the (explicit) labels in the corresponding index.rst + for rst_label_name in [ + 'label_1a', 'label_1b', 'label_2', 'label_3', + 'label_auto_1a', 'label_auto_1b', 'label_auto_2', 'label_auto_3', + ]: + tex_label_name = 'index:' + rst_label_name.replace('_', '-') + tex_label_code = r'\phantomsection\label{\detokenize{%s}}' % tex_label_name + assert content.count(tex_label_code) == 1, f'duplicated label: {tex_label_name!r}' + tested_labels.add(tex_label_code) + + # ensure that we did not forget any label to check + # and if so, report them nicely in case of failure + assert sorted(tested_labels) == sorted(output_labels) + + +@pytest.mark.sphinx('latex', testroot='domain-py-python_maximum_signature_line_length', + confoverrides={'python_maximum_signature_line_length': 23}) +def test_one_parameter_per_line(app, status, warning): + app.build(force_all=True) + result = (app.outdir / 'python.tex').read_text(encoding='utf8') + + # TODO: should these asserts check presence or absence of a final \sphinxparamcomma? + # signature of 23 characters is too short to trigger one-param-per-line mark-up + assert ('\\pysiglinewithargsret{\\sphinxbfcode{\\sphinxupquote{hello}}}' in result) + + assert ('\\pysigwithonelineperarg{\\sphinxbfcode{\\sphinxupquote{foo}}}' in result) diff --git a/tests/test_builders/test_build_linkcheck.py b/tests/test_builders/test_build_linkcheck.py new file mode 100644 index 0000000..c8d8515 --- /dev/null +++ b/tests/test_builders/test_build_linkcheck.py @@ -0,0 +1,1040 @@ +"""Test the build process with manpage builder with the test root.""" + +from __future__ import annotations + +import json +import re +import sys +import textwrap +import time +import wsgiref.handlers +from base64 import b64encode +from http.server import BaseHTTPRequestHandler +from queue import Queue +from unittest import mock + +import docutils +import pytest +from urllib3.poolmanager import PoolManager + +import sphinx.util.http_date +from sphinx.builders.linkcheck import ( + CheckRequest, + Hyperlink, + HyperlinkAvailabilityCheckWorker, + RateLimit, + compile_linkcheck_allowed_redirects, +) +from sphinx.deprecation import RemovedInSphinx80Warning +from sphinx.util import requests +from sphinx.util.console import strip_colors + +from tests.utils import CERT_FILE, serve_application + +ts_re = re.compile(r".*\[(?P<ts>.*)\].*") + + +class DefaultsHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + if self.path[1:].rstrip() in {"", "anchor.html"}: + self.send_response(200, "OK") + self.send_header("Content-Length", "0") + self.end_headers() + else: + self.send_response(404, "Not Found") + self.send_header("Content-Length", "0") + self.end_headers() + + def do_GET(self): + if self.path[1:].rstrip() == "": + content = b"ok\n\n" + elif self.path[1:].rstrip() == "anchor.html": + doc = '<!DOCTYPE html><html><body><a id="found"></a></body></html>' + content = doc.encode("utf-8") + else: + content = b"" + + if content: + self.send_response(200, "OK") + self.send_header("Content-Length", str(len(content))) + self.end_headers() + self.wfile.write(content) + else: + self.send_response(404, "Not Found") + self.send_header("Content-Length", "0") + self.end_headers() + + +class ConnectionMeasurement: + """Measure the number of distinct host connections created during linkchecking""" + + def __init__(self): + self.connections = set() + self.urllib3_connection_from_url = PoolManager.connection_from_url + self.patcher = mock.patch.object( + target=PoolManager, + attribute='connection_from_url', + new=self._collect_connections(), + ) + + def _collect_connections(self): + def connection_collector(obj, url): + connection = self.urllib3_connection_from_url(obj, url) + self.connections.add(connection) + return connection + return connection_collector + + def __enter__(self): + self.patcher.start() + return self + + def __exit__(self, *args, **kwargs): + for connection in self.connections: + connection.close() + self.patcher.stop() + + @property + def connection_count(self): + return len(self.connections) + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck', freshenv=True) +def test_defaults(app): + with serve_application(app, DefaultsHandler) as address: + with ConnectionMeasurement() as m: + app.build() + assert m.connection_count <= 5 + + # Text output + assert (app.outdir / 'output.txt').exists() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + + # looking for '#top' and '#does-not-exist' not found should fail + assert "Anchor 'top' not found" in content + assert "Anchor 'does-not-exist' not found" in content + # images should fail + assert f"Not Found for url: http://{address}/image.png" in content + assert f"Not Found for url: http://{address}/image2.png" in content + # looking for missing local file should fail + assert "[broken] path/to/notfound" in content + assert len(content.splitlines()) == 5 + + # JSON output + assert (app.outdir / 'output.json').exists() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + + rows = [json.loads(x) for x in content.splitlines()] + row = rows[0] + for attr in ("filename", "lineno", "status", "code", "uri", "info"): + assert attr in row + + assert len(content.splitlines()) == 10 + assert len(rows) == 10 + # the output order of the rows is not stable + # due to possible variance in network latency + rowsby = {row["uri"]: row for row in rows} + # looking for local file that exists should succeed + assert rowsby["conf.py"]["status"] == "working" + assert rowsby[f"http://{address}#!bar"] == { + 'filename': 'links.rst', + 'lineno': 5, + 'status': 'working', + 'code': 0, + 'uri': f'http://{address}#!bar', + 'info': '', + } + + def _missing_resource(filename: str, lineno: int): + return { + 'filename': 'links.rst', + 'lineno': lineno, + 'status': 'broken', + 'code': 0, + 'uri': f'http://{address}/{filename}', + 'info': f'404 Client Error: Not Found for url: http://{address}/{filename}', + } + accurate_linenumbers = docutils.__version_info__[:2] >= (0, 21) + image2_lineno = 12 if accurate_linenumbers else 13 + assert rowsby[f'http://{address}/image2.png'] == _missing_resource("image2.png", image2_lineno) + # looking for '#top' and '#does-not-exist' not found should fail + assert rowsby[f"http://{address}/#top"]["info"] == "Anchor 'top' not found" + assert rowsby[f"http://{address}/#top"]["status"] == "broken" + assert rowsby[f"http://{address}#does-not-exist"]["info"] == "Anchor 'does-not-exist' not found" + # images should fail + assert f"Not Found for url: http://{address}/image.png" in rowsby[f"http://{address}/image.png"]["info"] + # anchor should be found + assert rowsby[f'http://{address}/anchor.html#found'] == { + 'filename': 'links.rst', + 'lineno': 14, + 'status': 'working', + 'code': 0, + 'uri': f'http://{address}/anchor.html#found', + 'info': '', + } + + +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck', freshenv=True, + confoverrides={'linkcheck_anchors': False}) +def test_check_link_response_only(app): + with serve_application(app, DefaultsHandler) as address: + app.build() + + # JSON output + assert (app.outdir / 'output.json').exists() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + + rows = [json.loads(x) for x in content.splitlines()] + rowsby = {row["uri"]: row for row in rows} + assert rowsby[f"http://{address}/#top"]["status"] == "working" + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-too-many-retries', freshenv=True) +def test_too_many_retries(app): + with serve_application(app, DefaultsHandler) as address: + app.build() + + # Text output + assert (app.outdir / 'output.txt').exists() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + + # looking for non-existent URL should fail + assert " Max retries exceeded with url: /doesnotexist" in content + + # JSON output + assert (app.outdir / 'output.json').exists() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + + assert len(content.splitlines()) == 1 + row = json.loads(content) + # the output order of the rows is not stable + # due to possible variance in network latency + + # looking for non-existent URL should fail + assert row['filename'] == 'index.rst' + assert row['lineno'] == 1 + assert row['status'] == 'broken' + assert row['code'] == 0 + assert row['uri'] == f'https://{address}/doesnotexist' + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-raw-node', freshenv=True) +def test_raw_node(app): + with serve_application(app, OKHandler) as address: + # write an index file that contains a link back to this webserver's root + # URL. docutils will replace the raw node with the contents retrieved.. + # ..and then the linkchecker will check that the root URL is available. + index = (app.srcdir / "index.rst") + index.write_text( + ".. raw:: 'html'\n" + " :url: http://{address}/".format(address=address), + ) + app.build() + + # JSON output + assert (app.outdir / 'output.json').exists() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + + assert len(content.splitlines()) == 1 + row = json.loads(content) + + # raw nodes' url should be checked too + assert row == { + 'filename': 'index.rst', + 'lineno': 1, + 'status': 'working', + 'code': 0, + 'uri': f'http://{address}/', # the received rST contains a link to its' own URL + 'info': '', + } + + +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck-anchors-ignore', freshenv=True, + confoverrides={'linkcheck_anchors_ignore': ["^!", "^top$"]}) +def test_anchors_ignored(app): + with serve_application(app, OKHandler): + app.build() + + assert (app.outdir / 'output.txt').exists() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + + # expect all ok when excluding #top + assert not content + + +class AnchorsIgnoreForUrlHandler(BaseHTTPRequestHandler): + def do_HEAD(self): + if self.path in {'/valid', '/ignored'}: + self.send_response(200, "OK") + else: + self.send_response(404, "Not Found") + self.end_headers() + + def do_GET(self): + self.do_HEAD() + if self.path == '/valid': + self.wfile.write(b"<h1 id='valid-anchor'>valid anchor</h1>\n") + elif self.path == '/ignored': + self.wfile.write(b"no anchor but page exists\n") + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-anchors-ignore-for-url', freshenv=True) +def test_anchors_ignored_for_url(app): + with serve_application(app, AnchorsIgnoreForUrlHandler) as address: + app.config.linkcheck_anchors_ignore_for_url = [ # type: ignore[attr-defined] + f'http://{address}/ignored', # existing page + f'http://{address}/invalid', # unknown page + ] + app.build() + + assert (app.outdir / 'output.txt').exists() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + + attrs = ('filename', 'lineno', 'status', 'code', 'uri', 'info') + data = [json.loads(x) for x in content.splitlines()] + assert len(data) == 7 + assert all(all(attr in row for attr in attrs) for row in data) + + # rows may be unsorted due to network latency or + # the order the threads are processing the links + rows = {r['uri']: {'status': r['status'], 'info': r['info']} for r in data} + + assert rows[f'http://{address}/valid']['status'] == 'working' + assert rows[f'http://{address}/valid#valid-anchor']['status'] == 'working' + assert rows[f'http://{address}/valid#invalid-anchor'] == { + 'status': 'broken', + 'info': "Anchor 'invalid-anchor' not found", + } + + assert rows[f'http://{address}/ignored']['status'] == 'working' + assert rows[f'http://{address}/ignored#invalid-anchor']['status'] == 'working' + + assert rows[f'http://{address}/invalid'] == { + 'status': 'broken', + 'info': f'404 Client Error: Not Found for url: http://{address}/invalid', + } + assert rows[f'http://{address}/invalid#anchor'] == { + 'status': 'broken', + 'info': f'404 Client Error: Not Found for url: http://{address}/invalid', + } + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-anchor', freshenv=True) +def test_raises_for_invalid_status(app): + class InternalServerErrorHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_GET(self): + self.send_error(500, "Internal Server Error") + + with serve_application(app, InternalServerErrorHandler) as address: + app.build() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + assert content == ( + f"index.rst:1: [broken] http://{address}/#anchor: " + "500 Server Error: Internal Server Error " + f"for url: http://{address}/\n" + ) + + +def custom_handler(valid_credentials=(), success_criteria=lambda _: True): + """ + Returns an HTTP request handler that authenticates the client and then determines + an appropriate HTTP response code, based on caller-provided credentials and optional + success criteria, respectively. + """ + expected_token = None + if valid_credentials: + assert len(valid_credentials) == 2, "expected a pair of strings as credentials" + expected_token = b64encode(":".join(valid_credentials).encode()).decode("utf-8") + del valid_credentials + + class CustomHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def authenticated(method): + def method_if_authenticated(self): + if expected_token is None: + return method(self) + elif not self.headers["Authorization"]: + self.send_response(401, "Unauthorized") + self.end_headers() + elif self.headers["Authorization"] == f"Basic {expected_token}": + return method(self) + else: + self.send_response(403, "Forbidden") + self.send_header("Content-Length", "0") + self.end_headers() + + return method_if_authenticated + + @authenticated + def do_HEAD(self): + self.do_GET() + + @authenticated + def do_GET(self): + if success_criteria(self): + self.send_response(200, "OK") + self.send_header("Content-Length", "0") + else: + self.send_response(400, "Bad Request") + self.send_header("Content-Length", "0") + self.end_headers() + + return CustomHandler + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_auth_header_uses_first_match(app): + with serve_application(app, custom_handler(valid_credentials=("user1", "password"))) as address: + app.config.linkcheck_auth = [ # type: ignore[attr-defined] + (r'^$', ('no', 'match')), + (fr'^http://{re.escape(address)}/$', ('user1', 'password')), + (r'.*local.*', ('user2', 'hunter2')), + ] + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["status"] == "working" + + +@pytest.mark.filterwarnings('ignore::sphinx.deprecation.RemovedInSphinx80Warning') +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck-localserver', freshenv=True, + confoverrides={'linkcheck_allow_unauthorized': False}) +def test_unauthorized_broken(app): + with serve_application(app, custom_handler(valid_credentials=("user1", "password"))): + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["info"] == "unauthorized" + assert content["status"] == "broken" + + +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck-localserver', freshenv=True, + confoverrides={'linkcheck_auth': [(r'^$', ('user1', 'password'))]}) +def test_auth_header_no_match(app): + with ( + serve_application(app, custom_handler(valid_credentials=("user1", "password"))), + pytest.warns(RemovedInSphinx80Warning, match='linkcheck builder encountered an HTTP 401'), + ): + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + # This link is considered working based on the default linkcheck_allow_unauthorized=true + assert content["info"] == "unauthorized" + assert content["status"] == "working" + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_linkcheck_request_headers(app): + def check_headers(self): + if "X-Secret" in self.headers: + return False + return self.headers["Accept"] == "text/html" + + with serve_application(app, custom_handler(success_criteria=check_headers)) as address: + app.config.linkcheck_request_headers = { # type: ignore[attr-defined] + f"http://{address}/": {"Accept": "text/html"}, + "*": {"X-Secret": "open sesami"}, + } + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["status"] == "working" + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_linkcheck_request_headers_no_slash(app): + def check_headers(self): + if "X-Secret" in self.headers: + return False + return self.headers["Accept"] == "application/json" + + with serve_application(app, custom_handler(success_criteria=check_headers)) as address: + app.config.linkcheck_request_headers = { # type: ignore[attr-defined] + f"http://{address}": {"Accept": "application/json"}, + "*": {"X-Secret": "open sesami"}, + } + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["status"] == "working" + + +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck-localserver', freshenv=True, + confoverrides={'linkcheck_request_headers': { + "http://do.not.match.org": {"Accept": "application/json"}, + "*": {"X-Secret": "open sesami"}, + }}) +def test_linkcheck_request_headers_default(app): + def check_headers(self): + if self.headers["X-Secret"] != "open sesami": + return False + return self.headers["Accept"] != "application/json" + + with serve_application(app, custom_handler(success_criteria=check_headers)): + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["status"] == "working" + + +def make_redirect_handler(*, support_head): + class RedirectOnceHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + if support_head: + self.do_GET() + else: + self.send_response(405, "Method Not Allowed") + self.send_header("Content-Length", "0") + self.end_headers() + + def do_GET(self): + if self.path == "/?redirected=1": + self.send_response(204, "No content") + else: + self.send_response(302, "Found") + self.send_header("Location", "/?redirected=1") + self.send_header("Content-Length", "0") + self.end_headers() + + def log_date_time_string(self): + """Strip date and time from logged messages for assertions.""" + return "" + + return RedirectOnceHandler + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_follows_redirects_on_HEAD(app, capsys, warning): + with serve_application(app, make_redirect_handler(support_head=True)) as address: + app.build() + stdout, stderr = capsys.readouterr() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + assert content == ( + "index.rst:1: [redirected with Found] " + f"http://{address}/ to http://{address}/?redirected=1\n" + ) + assert stderr == textwrap.dedent( + """\ + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 302 - + 127.0.0.1 - - [] "HEAD /?redirected=1 HTTP/1.1" 204 - + """, + ) + assert warning.getvalue() == '' + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_follows_redirects_on_GET(app, capsys, warning): + with serve_application(app, make_redirect_handler(support_head=False)) as address: + app.build() + stdout, stderr = capsys.readouterr() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + assert content == ( + "index.rst:1: [redirected with Found] " + f"http://{address}/ to http://{address}/?redirected=1\n" + ) + assert stderr == textwrap.dedent( + """\ + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 405 - + 127.0.0.1 - - [] "GET / HTTP/1.1" 302 - + 127.0.0.1 - - [] "GET /?redirected=1 HTTP/1.1" 204 - + """, + ) + assert warning.getvalue() == '' + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-warn-redirects') +def test_linkcheck_allowed_redirects(app, warning): + with serve_application(app, make_redirect_handler(support_head=False)) as address: + app.config.linkcheck_allowed_redirects = {f'http://{address}/.*1': '.*'} # type: ignore[attr-defined] + compile_linkcheck_allowed_redirects(app, app.config) + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + rows = [json.loads(l) for l in fp] + + assert len(rows) == 2 + records = {row["uri"]: row for row in rows} + assert records[f"http://{address}/path1"]["status"] == "working" + assert records[f"http://{address}/path2"] == { + 'filename': 'index.rst', + 'lineno': 3, + 'status': 'redirected', + 'code': 302, + 'uri': f'http://{address}/path2', + 'info': f'http://{address}/?redirected=1', + } + + assert (f"index.rst:3: WARNING: redirect http://{address}/path2 - with Found to " + f"http://{address}/?redirected=1\n" in strip_colors(warning.getvalue())) + assert len(warning.getvalue().splitlines()) == 1 + + +class OKHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + self.send_response(200, "OK") + self.send_header("Content-Length", "0") + self.end_headers() + + def do_GET(self): + content = b"ok\n" + self.send_response(200, "OK") + self.send_header("Content-Length", str(len(content))) + self.end_headers() + self.wfile.write(content) + + +@mock.patch("sphinx.builders.linkcheck.requests.get", wraps=requests.get) +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_invalid_ssl(get_request, app): + # Link indicates SSL should be used (https) but the server does not handle it. + with serve_application(app, OKHandler) as address: + app.build() + assert not get_request.called + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content["status"] == "broken" + assert content["filename"] == "index.rst" + assert content["lineno"] == 1 + assert content["uri"] == f"https://{address}/" + assert "SSLError" in content["info"] + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_connect_to_selfsigned_fails(app): + with serve_application(app, OKHandler, tls_enabled=True) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content["status"] == "broken" + assert content["filename"] == "index.rst" + assert content["lineno"] == 1 + assert content["uri"] == f"https://{address}/" + assert "[SSL: CERTIFICATE_VERIFY_FAILED]" in content["info"] + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_connect_to_selfsigned_with_tls_verify_false(app): + app.config.tls_verify = False + with serve_application(app, OKHandler, tls_enabled=True) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content == { + "code": 0, + "status": "working", + "filename": "index.rst", + "lineno": 1, + "uri": f'https://{address}/', + "info": "", + } + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_connect_to_selfsigned_with_tls_cacerts(app): + app.config.tls_cacerts = CERT_FILE + with serve_application(app, OKHandler, tls_enabled=True) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content == { + "code": 0, + "status": "working", + "filename": "index.rst", + "lineno": 1, + "uri": f'https://{address}/', + "info": "", + } + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_connect_to_selfsigned_with_requests_env_var(monkeypatch, app): + monkeypatch.setenv("REQUESTS_CA_BUNDLE", CERT_FILE) + with serve_application(app, OKHandler, tls_enabled=True) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content == { + "code": 0, + "status": "working", + "filename": "index.rst", + "lineno": 1, + "uri": f'https://{address}/', + "info": "", + } + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver-https', freshenv=True) +def test_connect_to_selfsigned_nonexistent_cert_file(app): + app.config.tls_cacerts = "does/not/exist" + with serve_application(app, OKHandler, tls_enabled=True) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content == { + "code": 0, + "status": "broken", + "filename": "index.rst", + "lineno": 1, + "uri": f'https://{address}/', + "info": "Could not find a suitable TLS CA certificate bundle, invalid path: does/not/exist", + } + + +class InfiniteRedirectOnHeadHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + self.send_response(302, "Found") + self.send_header("Location", "/") + self.send_header("Content-Length", "0") + self.end_headers() + + def do_GET(self): + content = b"ok\n" + self.send_response(200, "OK") + self.send_header("Content-Length", str(len(content))) + self.end_headers() + self.wfile.write(content) + self.close_connection = True # we don't expect the client to read this response body + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_TooManyRedirects_on_HEAD(app, monkeypatch): + import requests.sessions + + monkeypatch.setattr(requests.sessions, "DEFAULT_REDIRECT_LIMIT", 5) + + with serve_application(app, InfiniteRedirectOnHeadHandler) as address: + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = json.load(fp) + assert content == { + "code": 0, + "status": "working", + "filename": "index.rst", + "lineno": 1, + "uri": f'http://{address}/', + "info": "", + } + + +def make_retry_after_handler(responses): + class RetryAfterHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + status, retry_after = responses.pop(0) + self.send_response(status) + if retry_after: + self.send_header('Retry-After', retry_after) + self.send_header("Content-Length", "0") + self.end_headers() + + def log_date_time_string(self): + """Strip date and time from logged messages for assertions.""" + return "" + + return RetryAfterHandler + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_too_many_requests_retry_after_int_delay(app, capsys, status): + with ( + serve_application(app, make_retry_after_handler([(429, "0"), (200, None)])) as address, + mock.patch("sphinx.builders.linkcheck.DEFAULT_DELAY", 0), + mock.patch("sphinx.builders.linkcheck.QUEUE_POLL_SECS", 0.01), + ): + app.build() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + assert json.loads(content) == { + "filename": "index.rst", + "lineno": 1, + "status": "working", + "code": 0, + "uri": f'http://{address}/', + "info": "", + } + rate_limit_log = f"-rate limited- http://{address}/ | sleeping...\n" + assert rate_limit_log in strip_colors(status.getvalue()) + _stdout, stderr = capsys.readouterr() + assert stderr == textwrap.dedent( + """\ + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 429 - + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 200 - + """, + ) + + +@pytest.mark.parametrize('tz', [None, 'GMT', 'GMT+3', 'GMT-3']) +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_too_many_requests_retry_after_HTTP_date(tz, app, monkeypatch, capsys): + retry_after = wsgiref.handlers.format_date_time(time.time()) + + with monkeypatch.context() as m: + if tz is not None: + m.setenv('TZ', tz) + if sys.platform != "win32": + time.tzset() + m.setattr(sphinx.util.http_date, '_GMT_OFFSET', + float(time.localtime().tm_gmtoff)) + + with serve_application(app, make_retry_after_handler([(429, retry_after), (200, None)])) as address: + app.build() + + content = (app.outdir / 'output.json').read_text(encoding='utf8') + assert json.loads(content) == { + "filename": "index.rst", + "lineno": 1, + "status": "working", + "code": 0, + "uri": f'http://{address}/', + "info": "", + } + _stdout, stderr = capsys.readouterr() + assert stderr == textwrap.dedent( + """\ + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 429 - + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 200 - + """, + ) + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_too_many_requests_retry_after_without_header(app, capsys): + with ( + serve_application(app, make_retry_after_handler([(429, None), (200, None)])) as address, + mock.patch("sphinx.builders.linkcheck.DEFAULT_DELAY", 0), + ): + app.build() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + assert json.loads(content) == { + "filename": "index.rst", + "lineno": 1, + "status": "working", + "code": 0, + "uri": f'http://{address}/', + "info": "", + } + _stdout, stderr = capsys.readouterr() + assert stderr == textwrap.dedent( + """\ + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 429 - + 127.0.0.1 - - [] "HEAD / HTTP/1.1" 200 - + """, + ) + + +@pytest.mark.sphinx( + 'linkcheck', testroot='linkcheck-localserver', freshenv=True, + confoverrides={ + 'linkcheck_report_timeouts_as_broken': False, + 'linkcheck_timeout': 0.01, + } +) +def test_requests_timeout(app): + class DelayedResponseHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_GET(self): + time.sleep(0.2) # wait before sending any response data + self.send_response(200, "OK") + self.send_header("Content-Length", "0") + self.end_headers() + + with serve_application(app, DelayedResponseHandler): + app.build() + + with open(app.outdir / "output.json", encoding="utf-8") as fp: + content = json.load(fp) + + assert content["status"] == "timeout" + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_too_many_requests_user_timeout(app): + app.config.linkcheck_rate_limit_timeout = 0.0 + with serve_application(app, make_retry_after_handler([(429, None)])) as address: + app.build() + content = (app.outdir / 'output.json').read_text(encoding='utf8') + assert json.loads(content) == { + "filename": "index.rst", + "lineno": 1, + "status": "broken", + "code": 0, + "uri": f'http://{address}/', + "info": f"429 Client Error: Too Many Requests for url: http://{address}/", + } + + +class FakeResponse: + headers: dict[str, str] = {} + url = "http://localhost/" + + +def test_limit_rate_default_sleep(app): + worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), {}) + with mock.patch('time.time', return_value=0.0): + next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) + assert next_check == 60.0 + + +def test_limit_rate_user_max_delay(app): + app.config.linkcheck_rate_limit_timeout = 0.0 + worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), {}) + next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) + assert next_check is None + + +def test_limit_rate_doubles_previous_wait_time(app): + rate_limits = {"localhost": RateLimit(60.0, 0.0)} + worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), rate_limits) + with mock.patch('time.time', return_value=0.0): + next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) + assert next_check == 120.0 + + +def test_limit_rate_clips_wait_time_to_max_time(app): + app.config.linkcheck_rate_limit_timeout = 90.0 + rate_limits = {"localhost": RateLimit(60.0, 0.0)} + worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), rate_limits) + with mock.patch('time.time', return_value=0.0): + next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) + assert next_check == 90.0 + + +def test_limit_rate_bails_out_after_waiting_max_time(app): + app.config.linkcheck_rate_limit_timeout = 90.0 + rate_limits = {"localhost": RateLimit(90.0, 0.0)} + worker = HyperlinkAvailabilityCheckWorker(app.config, Queue(), Queue(), rate_limits) + next_check = worker.limit_rate(FakeResponse.url, FakeResponse.headers.get("Retry-After")) + assert next_check is None + + +@mock.patch('sphinx.util.requests.requests.Session.get_adapter') +def test_connection_contention(get_adapter, app, capsys): + # Create a shared, but limited-size, connection pool + import requests + get_adapter.return_value = requests.adapters.HTTPAdapter(pool_maxsize=1) + + # Set an upper-bound on socket timeouts globally + import socket + socket.setdefaulttimeout(5) + + # Create parallel consumer threads + with serve_application(app, make_redirect_handler(support_head=True)) as address: + + # Place a workload into the linkcheck queue + link_count = 10 + rqueue, wqueue = Queue(), Queue() + for _ in range(link_count): + wqueue.put(CheckRequest(0, Hyperlink(f"http://{address}", "test", "test.rst", 1))) + + begin, checked = time.time(), [] + threads = [ + HyperlinkAvailabilityCheckWorker( + config=app.config, + rqueue=rqueue, + wqueue=wqueue, + rate_limits={}, + ) + for _ in range(10) + ] + for thread in threads: + thread.start() + while time.time() < begin + 5 and len(checked) < link_count: + checked.append(rqueue.get(timeout=5)) + for thread in threads: + thread.join(timeout=0) + + # Ensure that all items were consumed within the time limit + _, stderr = capsys.readouterr() + assert len(checked) == link_count + assert "TimeoutError" not in stderr + + +class ConnectionResetHandler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_HEAD(self): + self.close_connection = True + + def do_GET(self): + self.send_response(200, "OK") + self.send_header("Content-Length", "0") + self.end_headers() + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-localserver', freshenv=True) +def test_get_after_head_raises_connection_error(app): + with serve_application(app, ConnectionResetHandler) as address: + app.build() + content = (app.outdir / 'output.txt').read_text(encoding='utf8') + assert not content + content = (app.outdir / 'output.json').read_text(encoding='utf8') + assert json.loads(content) == { + "filename": "index.rst", + "lineno": 1, + "status": "working", + "code": 0, + "uri": f'http://{address}/', + "info": "", + } + + +@pytest.mark.sphinx('linkcheck', testroot='linkcheck-documents_exclude', freshenv=True) +def test_linkcheck_exclude_documents(app): + with serve_application(app, DefaultsHandler): + app.build() + + with open(app.outdir / 'output.json', encoding='utf-8') as fp: + content = [json.loads(record) for record in fp] + + assert len(content) == 2 + assert { + 'filename': 'broken_link.rst', + 'lineno': 4, + 'status': 'ignored', + 'code': 0, + 'uri': 'https://www.sphinx-doc.org/this-is-a-broken-link', + 'info': 'broken_link matched ^broken_link$ from linkcheck_exclude_documents', + } in content + assert { + 'filename': 'br0ken_link.rst', + 'lineno': 4, + 'status': 'ignored', + 'code': 0, + 'uri': 'https://www.sphinx-doc.org/this-is-another-broken-link', + 'info': 'br0ken_link matched br[0-9]ken_link from linkcheck_exclude_documents', + } in content diff --git a/tests/test_builders/test_build_manpage.py b/tests/test_builders/test_build_manpage.py new file mode 100644 index 0000000..7172281 --- /dev/null +++ b/tests/test_builders/test_build_manpage.py @@ -0,0 +1,104 @@ +"""Test the build process with manpage builder with the test root.""" + +import docutils +import pytest + +from sphinx.builders.manpage import default_man_pages +from sphinx.config import Config + + +@pytest.mark.sphinx('man') +def test_all(app, status, warning): + app.build(force_all=True) + assert (app.outdir / 'sphinxtests.1').exists() + + content = (app.outdir / 'sphinxtests.1').read_text(encoding='utf8') + assert r'\fBprint \fP\fIi\fP\fB\en\fP' in content + assert r'\fBmanpage\en\fP' in content + + # heading (title + description) + assert r'sphinxtests \- Sphinx <Tests> 0.6alpha1' in content + + # term of definition list including nodes.strong + assert '\n.B term1\n' in content + assert '\nterm2 (\\fBstronged partially\\fP)\n' in content + + # test samp with braces + assert '\n\\fIvariable_only\\fP\n' in content + assert '\n\\fIvariable\\fP\\fB and text\\fP\n' in content + assert '\n\\fBShow \\fP\\fIvariable\\fP\\fB in the middle\\fP\n' in content + + assert 'Footnotes' not in content + + +@pytest.mark.sphinx('man', testroot='basic', + confoverrides={'man_pages': [('index', 'title', None, [], 1)]}) +def test_man_pages_empty_description(app, status, warning): + app.build(force_all=True) + + content = (app.outdir / 'title.1').read_text(encoding='utf8') + assert r'title \-' not in content + + +@pytest.mark.sphinx('man', testroot='basic', + confoverrides={'man_make_section_directory': True}) +def test_man_make_section_directory(app, status, warning): + app.build() + assert (app.outdir / 'man1' / 'python.1').exists() + + +@pytest.mark.sphinx('man', testroot='directive-code') +def test_captioned_code_block(app, status, warning): + app.build(force_all=True) + content = (app.outdir / 'python.1').read_text(encoding='utf8') + + if docutils.__version_info__[:2] < (0, 21): + expected = """\ +.sp +caption \\fItest\\fP rb +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +def ruby? + false +end +.ft P +.fi +.UNINDENT +.UNINDENT +""" + else: + expected = """\ +.sp +caption \\fItest\\fP rb +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +def ruby? + false +end +.EE +.UNINDENT +.UNINDENT +""" + + assert expected in content + + +def test_default_man_pages(): + config = Config({'project': 'STASI™ Documentation', + 'author': "Wolfgang Schäuble & G'Beckstein", + 'release': '1.0'}) + expected = [('index', 'stasi', 'STASI™ Documentation 1.0', + ["Wolfgang Schäuble & G'Beckstein"], 1)] + assert default_man_pages(config) == expected + + +@pytest.mark.sphinx('man', testroot='markup-rubric') +def test_rubric(app, status, warning): + app.build() + content = (app.outdir / 'python.1').read_text(encoding='utf8') + assert 'This is a rubric\n' in content diff --git a/tests/test_builders/test_build_texinfo.py b/tests/test_builders/test_build_texinfo.py new file mode 100644 index 0000000..f9effb2 --- /dev/null +++ b/tests/test_builders/test_build_texinfo.py @@ -0,0 +1,130 @@ +"""Test the build process with Texinfo builder with the test root.""" + +import re +import subprocess +from pathlib import Path +from subprocess import CalledProcessError +from unittest.mock import Mock + +import pytest + +from sphinx.builders.texinfo import default_texinfo_documents +from sphinx.config import Config +from sphinx.util.docutils import new_document +from sphinx.writers.texinfo import TexinfoTranslator + + +@pytest.mark.sphinx('texinfo') +def test_texinfo(app, status, warning): + TexinfoTranslator.ignore_missing_images = True + app.build(force_all=True) + result = (app.outdir / 'sphinxtests.texi').read_text(encoding='utf8') + assert ('@anchor{markup doc}@anchor{11}' + '@anchor{markup id1}@anchor{12}' + '@anchor{markup testing-various-markup}@anchor{13}' in result) + assert 'Footnotes' not in result + # now, try to run makeinfo over it + try: + args = ['makeinfo', '--no-split', 'sphinxtests.texi'] + subprocess.run(args, capture_output=True, cwd=app.outdir, check=True) + except OSError as exc: + raise pytest.skip.Exception from exc # most likely makeinfo was not found + except CalledProcessError as exc: + print(exc.stdout) + print(exc.stderr) + msg = f'makeinfo exited with return code {exc.retcode}' + raise AssertionError(msg) from exc + + +@pytest.mark.sphinx('texinfo', testroot='markup-rubric') +def test_texinfo_rubric(app, status, warning): + app.build() + + output = (app.outdir / 'python.texi').read_text(encoding='utf8') + assert '@heading This is a rubric' in output + assert '@heading This is a multiline rubric' in output + + +@pytest.mark.sphinx('texinfo', testroot='markup-citation') +def test_texinfo_citation(app, status, warning): + app.build(force_all=True) + + output = (app.outdir / 'python.texi').read_text(encoding='utf8') + assert 'This is a citation ref; @ref{1,,[CITE1]} and @ref{2,,[CITE2]}.' in output + assert ('@anchor{index cite1}@anchor{1}@w{(CITE1)} \n' + 'This is a citation\n') in output + assert ('@anchor{index cite2}@anchor{2}@w{(CITE2)} \n' + 'This is a multiline citation\n') in output + + +def test_default_texinfo_documents(): + config = Config({'project': 'STASI™ Documentation', + 'author': "Wolfgang Schäuble & G'Beckstein"}) + expected = [('index', 'stasi', 'STASI™ Documentation', + "Wolfgang Schäuble & G'Beckstein", 'stasi', + 'One line description of project', 'Miscellaneous')] + assert default_texinfo_documents(config) == expected + + +@pytest.mark.sphinx('texinfo') +def test_texinfo_escape_id(app, status, warning): + settings = Mock(title='', + texinfo_dir_entry='', + texinfo_elements={}) + document = new_document('', settings) + translator = app.builder.create_translator(document, app.builder) + + assert translator.escape_id('Hello world') == 'Hello world' + assert translator.escape_id('Hello world') == 'Hello world' + assert translator.escape_id('Hello Sphinx world') == 'Hello Sphinx world' + assert translator.escape_id('Hello:world') == 'Hello world' + assert translator.escape_id('Hello(world)') == 'Hello world' + assert translator.escape_id('Hello world.') == 'Hello world' + assert translator.escape_id('.') == '.' + + +@pytest.mark.sphinx('texinfo', testroot='footnotes') +def test_texinfo_footnote(app, status, warning): + app.build(force_all=True) + + output = (app.outdir / 'python.texi').read_text(encoding='utf8') + assert 'First footnote: @footnote{\nFirst\n}' in output + + +@pytest.mark.sphinx('texinfo') +def test_texinfo_xrefs(app, status, warning): + app.build(force_all=True) + output = (app.outdir / 'sphinxtests.texi').read_text(encoding='utf8') + assert re.search(r'@ref{\w+,,--plugin\.option}', output) + + # Now rebuild it without xrefs + app.config.texinfo_cross_references = False + app.build(force_all=True) + output = (app.outdir / 'sphinxtests.texi').read_text(encoding='utf8') + assert not re.search(r'@ref{\w+,,--plugin\.option}', output) + assert 'Link to perl +p, --ObjC++, --plugin.option, create-auth-token, arg and -j' in output + + +@pytest.mark.sphinx('texinfo', testroot='root') +def test_texinfo_samp_with_variable(app, status, warning): + app.build() + + output = (app.outdir / 'sphinxtests.texi').read_text(encoding='utf8') + + assert '@code{@var{variable_only}}' in output + assert '@code{@var{variable} and text}' in output + assert '@code{Show @var{variable} in the middle}' in output + + +@pytest.mark.sphinx('texinfo', testroot='images') +def test_copy_images(app, status, warning): + app.build() + + images_dir = Path(app.outdir) / 'python-figures' + images = {image.name for image in images_dir.rglob('*')} + images.discard('python-logo.png') + assert images == { + 'img.png', + 'rimg.png', + 'testimäge.png', + } diff --git a/tests/test_builders/test_build_text.py b/tests/test_builders/test_build_text.py new file mode 100644 index 0000000..6dc0d03 --- /dev/null +++ b/tests/test_builders/test_build_text.py @@ -0,0 +1,278 @@ +"""Test the build process with Text builder with the test root.""" + +import pytest +from docutils.utils import column_width + +from sphinx.writers.text import MAXWIDTH, Cell, Table + + +def with_text_app(*args, **kw): + default_kw = { + 'buildername': 'text', + 'testroot': 'build-text', + } + default_kw.update(kw) + return pytest.mark.sphinx(*args, **default_kw) + + +@with_text_app() +def test_maxwitdh_with_prefix(app, status, warning): + app.build() + result = (app.outdir / 'maxwidth.txt').read_text(encoding='utf8') + + lines = result.splitlines() + line_widths = [column_width(line) for line in lines] + assert max(line_widths) < MAXWIDTH + assert lines[0].startswith('See also:') + assert lines[1].startswith('') + assert lines[2].startswith(' ham') + assert lines[3].startswith(' ham') + assert lines[4] == '' + assert lines[5].startswith('* ham') + assert lines[6].startswith(' ham') + assert lines[7] == '' + assert lines[8].startswith('* ham') + assert lines[9].startswith(' ham') + assert lines[10] == '' + assert lines[11].startswith('spam egg') + + +@with_text_app() +def test_lineblock(app, status, warning): + # regression test for #1109: need empty line after line block + app.build() + result = (app.outdir / 'lineblock.txt').read_text(encoding='utf8') + expect = ( + "* one\n" + "\n" + " line-block 1\n" + " line-block 2\n" + "\n" + "followed paragraph.\n" + ) + assert result == expect + + +@with_text_app() +def test_nonascii_title_line(app, status, warning): + app.build() + result = (app.outdir / 'nonascii_title.txt').read_text(encoding='utf8') + expect_underline = '*********' + result_underline = result.splitlines()[1].strip() + assert expect_underline == result_underline + + +@with_text_app() +def test_nonascii_table(app, status, warning): + app.build() + result = (app.outdir / 'nonascii_table.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + line_widths = [column_width(line) for line in lines] + assert len(set(line_widths)) == 1 # same widths + + +@with_text_app() +def test_nonascii_maxwidth(app, status, warning): + app.build() + result = (app.outdir / 'nonascii_maxwidth.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + line_widths = [column_width(line) for line in lines] + assert max(line_widths) < MAXWIDTH + + +def test_table_builder(): + table = Table([6, 6]) + table.add_cell(Cell("foo")) + table.add_cell(Cell("bar")) + table_str = str(table).split("\n") + assert table_str[0] == "+--------+--------+" + assert table_str[1] == "| foo | bar |" + assert table_str[2] == "+--------+--------+" + assert repr(table).count("<Cell ") == 2 + + +def test_table_separator(): + table = Table([6, 6]) + table.add_cell(Cell("foo")) + table.add_cell(Cell("bar")) + table.set_separator() + table.add_row() + table.add_cell(Cell("FOO")) + table.add_cell(Cell("BAR")) + table_str = str(table).split("\n") + assert table_str[0] == "+--------+--------+" + assert table_str[1] == "| foo | bar |" + assert table_str[2] == "|========|========|" + assert table_str[3] == "| FOO | BAR |" + assert table_str[4] == "+--------+--------+" + assert repr(table).count("<Cell ") == 4 + + +def test_table_cell(): + cell = Cell("Foo bar baz") + cell.wrap(3) + assert "Cell" in repr(cell) + assert cell.wrapped == ["Foo", "bar", "baz"] + + +@with_text_app() +def test_table_with_empty_cell(app, status, warning): + app.build() + result = (app.outdir / 'table.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + assert lines[0] == "+-------+-------+" + assert lines[1] == "| XXX | XXX |" + assert lines[2] == "+-------+-------+" + assert lines[3] == "| | XXX |" + assert lines[4] == "+-------+-------+" + assert lines[5] == "| XXX | |" + assert lines[6] == "+-------+-------+" + + +@with_text_app() +def test_table_with_rowspan(app, status, warning): + app.build() + result = (app.outdir / 'table_rowspan.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + assert lines[0] == "+-------+-------+" + assert lines[1] == "| XXXXXXXXX |" + assert lines[2] == "+-------+-------+" + assert lines[3] == "| | XXX |" + assert lines[4] == "+-------+-------+" + assert lines[5] == "| XXX | |" + assert lines[6] == "+-------+-------+" + + +@with_text_app() +def test_table_with_colspan(app, status, warning): + app.build() + result = (app.outdir / 'table_colspan.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + assert lines[0] == "+-------+-------+" + assert lines[1] == "| XXX | XXX |" + assert lines[2] == "+-------+-------+" + assert lines[3] == "| | XXX |" + assert lines[4] == "+-------+ |" + assert lines[5] == "| XXX | |" + assert lines[6] == "+-------+-------+" + + +@with_text_app() +def test_table_with_colspan_left(app, status, warning): + app.build() + result = (app.outdir / 'table_colspan_left.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + assert lines[0] == "+-------+-------+" + assert lines[1] == "| XXX | XXX |" + assert lines[2] == "+-------+-------+" + assert lines[3] == "| XXX | XXX |" + assert lines[4] == "| +-------+" + assert lines[5] == "| | |" + assert lines[6] == "+-------+-------+" + + +@with_text_app() +def test_table_with_colspan_and_rowspan(app, status, warning): + app.build() + result = (app.outdir / 'table_colspan_and_rowspan.txt').read_text(encoding='utf8') + lines = [line.strip() for line in result.splitlines() if line.strip()] + assert result + assert lines[0] == "+-------+-------+-------+" + assert lines[1] == "| AAA | BBB |" + assert lines[2] == "+-------+-------+ |" + assert lines[3] == "| DDD | XXX | |" + assert lines[4] == "| +-------+-------+" + assert lines[5] == "| | CCC |" + assert lines[6] == "+-------+-------+-------+" + + +@with_text_app() +def test_list_items_in_admonition(app, status, warning): + app.build() + result = (app.outdir / 'listitems.txt').read_text(encoding='utf8') + lines = [line.rstrip() for line in result.splitlines()] + assert lines[0] == "See also:" + assert lines[1] == "" + assert lines[2] == " * item 1" + assert lines[3] == "" + assert lines[4] == " * item 2" + + +@with_text_app() +def test_secnums(app, status, warning): + app.build(force_all=True) + index = (app.outdir / 'index.txt').read_text(encoding='utf8') + lines = index.splitlines() + assert lines[0] == "* 1. Section A" + assert lines[1] == "" + assert lines[2] == "* 2. Section B" + assert lines[3] == "" + assert lines[4] == " * 2.1. Sub Ba" + assert lines[5] == "" + assert lines[6] == " * 2.2. Sub Bb" + doc2 = (app.outdir / 'doc2.txt').read_text(encoding='utf8') + expect = ( + "2. Section B\n" + "************\n" + "\n" + "\n" + "2.1. Sub Ba\n" + "===========\n" + "\n" + "\n" + "2.2. Sub Bb\n" + "===========\n" + ) + assert doc2 == expect + + app.config.text_secnumber_suffix = " " + app.build(force_all=True) + index = (app.outdir / 'index.txt').read_text(encoding='utf8') + lines = index.splitlines() + assert lines[0] == "* 1 Section A" + assert lines[1] == "" + assert lines[2] == "* 2 Section B" + assert lines[3] == "" + assert lines[4] == " * 2.1 Sub Ba" + assert lines[5] == "" + assert lines[6] == " * 2.2 Sub Bb" + doc2 = (app.outdir / 'doc2.txt').read_text(encoding='utf8') + expect = ( + "2 Section B\n" + "***********\n" + "\n" + "\n" + "2.1 Sub Ba\n" + "==========\n" + "\n" + "\n" + "2.2 Sub Bb\n" + "==========\n" + ) + assert doc2 == expect + + app.config.text_add_secnumbers = False + app.build(force_all=True) + index = (app.outdir / 'index.txt').read_text(encoding='utf8') + lines = index.splitlines() + assert lines[0] == "* Section A" + assert lines[1] == "" + assert lines[2] == "* Section B" + assert lines[3] == "" + assert lines[4] == " * Sub Ba" + assert lines[5] == "" + assert lines[6] == " * Sub Bb" + doc2 = (app.outdir / 'doc2.txt').read_text(encoding='utf8') + expect = ( + "Section B\n" + "*********\n" + "\n" + "\n" + "Sub Ba\n" + "======\n" + "\n" + "\n" + "Sub Bb\n" + "======\n" + ) + assert doc2 == expect diff --git a/tests/test_builders/test_build_warnings.py b/tests/test_builders/test_build_warnings.py new file mode 100644 index 0000000..eeb7e9d --- /dev/null +++ b/tests/test_builders/test_build_warnings.py @@ -0,0 +1,89 @@ +import os +import re +import sys + +import pytest + +from sphinx.util.console import strip_colors + +ENV_WARNINGS = """\ +{root}/autodoc_fodder.py:docstring of autodoc_fodder.MarkupError:\\d+: \ +WARNING: Explicit markup ends without a blank line; unexpected unindent. +{root}/index.rst:\\d+: WARNING: Encoding 'utf-8-sig' used for reading included \ +file '{root}/wrongenc.inc' seems to be wrong, try giving an :encoding: option +{root}/index.rst:\\d+: WARNING: invalid single index entry '' +{root}/index.rst:\\d+: WARNING: image file not readable: foo.png +{root}/index.rst:\\d+: WARNING: download file not readable: {root}/nonexisting.png +{root}/undecodable.rst:\\d+: WARNING: undecodable source characters, replacing \ +with "\\?": b?'here: >>>(\\\\|/)xbb<<<((\\\\|/)r)?' +""" + +HTML_WARNINGS = ENV_WARNINGS + """\ +{root}/index.rst:\\d+: WARNING: unknown option: '&option' +{root}/index.rst:\\d+: WARNING: citation not found: missing +{root}/index.rst:\\d+: WARNING: a suitable image for html builder not found: foo.\\* +{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode. +""" + +LATEX_WARNINGS = ENV_WARNINGS + """\ +{root}/index.rst:\\d+: WARNING: unknown option: '&option' +{root}/index.rst:\\d+: WARNING: citation not found: missing +{root}/index.rst:\\d+: WARNING: a suitable image for latex builder not found: foo.\\* +{root}/index.rst:\\d+: WARNING: Lexing literal_block ".*" as "c" resulted in an error at token: ".*". Retrying in relaxed mode. +""" + +TEXINFO_WARNINGS = ENV_WARNINGS + """\ +{root}/index.rst:\\d+: WARNING: unknown option: '&option' +{root}/index.rst:\\d+: WARNING: citation not found: missing +{root}/index.rst:\\d+: WARNING: a suitable image for texinfo builder not found: foo.\\* +{root}/index.rst:\\d+: WARNING: a suitable image for texinfo builder not found: \ +\\['application/pdf', 'image/svg\\+xml'\\] \\(svgimg.\\*\\) +""" + + +def _check_warnings(expected_warnings: str, warning: str) -> None: + warnings = strip_colors(re.sub(re.escape(os.sep) + '{1,2}', '/', warning)) + assert re.match(f'{expected_warnings}$', warnings), ( + "Warnings don't match:\n" + + f'--- Expected (regex):\n{expected_warnings}\n' + + f'--- Got:\n{warnings}' + ) + sys.modules.pop('autodoc_fodder', None) + + +@pytest.mark.sphinx('html', testroot='warnings', freshenv=True) +def test_html_warnings(app, warning): + app.build(force_all=True) + warnings_exp = HTML_WARNINGS.format(root=re.escape(app.srcdir.as_posix())) + _check_warnings(warnings_exp, warning.getvalue()) + + +@pytest.mark.sphinx('latex', testroot='warnings', freshenv=True) +def test_latex_warnings(app, warning): + app.build(force_all=True) + warnings_exp = LATEX_WARNINGS.format(root=re.escape(app.srcdir.as_posix())) + _check_warnings(warnings_exp, warning.getvalue()) + + +@pytest.mark.sphinx('texinfo', testroot='warnings', freshenv=True) +def test_texinfo_warnings(app, warning): + app.build(force_all=True) + warnings_exp = TEXINFO_WARNINGS.format(root=re.escape(app.srcdir.as_posix())) + _check_warnings(warnings_exp, warning.getvalue()) + + +def test_uncacheable_config_warning(make_app, tmp_path): + """Test that an unpickleable config value raises a warning.""" + tmp_path.joinpath('conf.py').write_text("""\ +my_config = lambda: None +show_warning_types = True +def setup(app): + app.add_config_value('my_config', None, 'env') + """, encoding='utf-8') + tmp_path.joinpath('index.rst').write_text('Test\n====\n', encoding='utf-8') + app = make_app(srcdir=tmp_path) + app.build() + assert strip_colors(app.warning.getvalue()).strip() == ( + "WARNING: cannot cache unpickable configuration value: 'my_config' " + "(because it contains a function, class, or module object) [config.cache]" + ) diff --git a/tests/test_builders/test_builder.py b/tests/test_builders/test_builder.py new file mode 100644 index 0000000..ee946a5 --- /dev/null +++ b/tests/test_builders/test_builder.py @@ -0,0 +1,44 @@ +"""Test the Builder class.""" + +import sys + +import pytest + + +@pytest.mark.sphinx('dummy', srcdir="test_builder", freshenv=True) +def test_incremental_reading(app): + # first reading + updated = app.builder.read() + assert set(updated) == app.env.found_docs == set(app.env.all_docs) + assert updated == sorted(updated) # sorted by alphanumeric + + # test if exclude_patterns works ok + assert 'subdir/excluded' not in app.env.found_docs + + # before second reading, add, modify and remove source files + (app.srcdir / 'new.txt').write_text('New file\n========\n', encoding='utf8') + app.env.all_docs['index'] = 0 # mark as modified + (app.srcdir / 'autodoc.txt').unlink() + + # second reading + updated = app.builder.read() + + assert set(updated) == {'index', 'new'} + assert 'autodoc' not in app.env.all_docs + assert 'autodoc' not in app.env.found_docs + + +@pytest.mark.sphinx('dummy', testroot='warnings', freshenv=True) +def test_incremental_reading_for_missing_files(app): + # first reading + updated = app.builder.read() + assert set(updated) == app.env.found_docs == set(app.env.all_docs) + + # second reading + updated = app.builder.read() + + # "index" is listed up to updated because it contains references + # to nonexisting downloadable or image files + assert set(updated) == {'index'} + + sys.modules.pop('autodoc_fodder', None) diff --git a/tests/test_builders/xpath_data.py b/tests/test_builders/xpath_data.py new file mode 100644 index 0000000..30f8e07 --- /dev/null +++ b/tests/test_builders/xpath_data.py @@ -0,0 +1,8 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from typing import Final + +FIGURE_CAPTION: Final[str] = ".//figure/figcaption/p" diff --git a/tests/test_builders/xpath_util.py b/tests/test_builders/xpath_util.py new file mode 100644 index 0000000..7525c19 --- /dev/null +++ b/tests/test_builders/xpath_util.py @@ -0,0 +1,79 @@ +from __future__ import annotations + +import re +import textwrap +from typing import TYPE_CHECKING +from xml.etree.ElementTree import tostring + +if TYPE_CHECKING: + import os + from collections.abc import Callable, Iterable, Sequence + from xml.etree.ElementTree import Element, ElementTree + + +def _get_text(node: Element) -> str: + if node.text is not None: + # the node has only one text + return node.text + + # the node has tags and text; gather texts just under the node + return ''.join(n.tail or '' for n in node) + + +def _prettify(nodes: Iterable[Element]) -> str: + def pformat(node: Element) -> str: + return tostring(node, encoding='unicode', method='html') + + return ''.join(f'(i={index}) {pformat(node)}\n' for index, node in enumerate(nodes)) + + +def check_xpath( + etree: ElementTree, + filename: str | os.PathLike[str], + xpath: str, + check: str | re.Pattern[str] | Callable[[Sequence[Element]], None] | None, + be_found: bool = True, + *, + min_count: int = 1, +) -> None: + """Check that one or more nodes satisfy a predicate. + + :param etree: The element tree. + :param filename: The element tree source name (for errors only). + :param xpath: An XPath expression to use. + :param check: Optional regular expression or a predicate the nodes must validate. + :param be_found: If false, negate the predicate. + :param min_count: Minimum number of nodes expected to satisfy the predicate. + + * If *check* is empty (``''``), only the minimum count is checked. + * If *check* is ``None``, no node should satisfy the XPath expression. + """ + nodes = etree.findall(xpath) + assert isinstance(nodes, list) + + if check is None: + # use == to have a nice pytest diff + assert nodes == [], f'found nodes matching xpath {xpath!r} in file {filename}' + return + + assert len(nodes) >= min_count, (f'expecting at least {min_count} node(s) ' + f'to satisfy {xpath!r} in file {filename}') + + if check == '': + return + + if callable(check): + check(nodes) + return + + rex = re.compile(check) + if be_found: + if any(rex.search(_get_text(node)) for node in nodes): + return + else: + if all(not rex.search(_get_text(node)) for node in nodes): + return + + ctx = textwrap.indent(_prettify(nodes), ' ' * 2) + msg = f'{check!r} not found in any node matching {xpath!r} in file {filename}:\n{ctx}' + raise AssertionError(msg) |