""" Test various Sphinx-specific markup extensions. :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ import re import pytest from docutils import frontend, nodes, utils from docutils.parsers.rst import Parser as RstParser from sphinx import addnodes from sphinx.builders.html.transforms import KeyboardTransform from sphinx.builders.latex import LaTeXBuilder from sphinx.roles import XRefRole from sphinx.testing.util import Struct, assert_node from sphinx.transforms import SphinxSmartQuotes from sphinx.util import docutils, texescape from sphinx.util.docutils import sphinx_domains from sphinx.writers.html import HTMLTranslator, HTMLWriter from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter @pytest.fixture def settings(app): texescape.init() # otherwise done by the latex builder optparser = frontend.OptionParser( components=(RstParser, HTMLWriter, LaTeXWriter)) settings = optparser.get_default_values() settings.smart_quotes = True settings.env = app.builder.env settings.env.temp_data['docname'] = 'dummy' settings.contentsname = 'dummy' settings.rfc_base_url = 'http://datatracker.ietf.org/doc/html/' domain_context = sphinx_domains(settings.env) domain_context.enable() yield settings domain_context.disable() @pytest.fixture def new_document(settings): def create(): document = utils.new_document('test data', settings) document['file'] = 'dummy' return document return create @pytest.fixture def inliner(new_document): document = new_document() document.reporter.get_source_and_line = lambda line=1: ('dummy.rst', line) return Struct(document=document, reporter=document.reporter) @pytest.fixture def parse(new_document): def parse_(rst): document = new_document() parser = RstParser() parser.parse(rst, document) SphinxSmartQuotes(document, startnode=None).apply() for msg in list(document.findall(nodes.system_message)): if msg['level'] == 1: msg.replace_self([]) return document return parse_ # since we're not resolving the markup afterwards, these nodes may remain class ForgivingTranslator: def visit_pending_xref(self, node): pass def depart_pending_xref(self, node): pass class ForgivingHTMLTranslator(HTMLTranslator, ForgivingTranslator): pass class ForgivingLaTeXTranslator(LaTeXTranslator, ForgivingTranslator): pass @pytest.fixture def verify_re_html(app, parse): def verify(rst, html_expected): document = parse(rst) KeyboardTransform(document).apply() html_translator = ForgivingHTMLTranslator(document, app.builder) document.walkabout(html_translator) html_translated = ''.join(html_translator.fragment).strip() assert re.match(html_expected, html_translated), 'from ' + rst return verify @pytest.fixture def verify_re_latex(app, parse): def verify(rst, latex_expected): document = parse(rst) app.builder = LaTeXBuilder(app) app.builder.set_environment(app.env) app.builder.init() theme = app.builder.themes.get('manual') latex_translator = ForgivingLaTeXTranslator(document, app.builder, theme) latex_translator.first_document = -1 # don't write \begin{document} document.walkabout(latex_translator) latex_translated = ''.join(latex_translator.body).strip() assert re.match(latex_expected, latex_translated), 'from ' + repr(rst) return verify @pytest.fixture def verify_re(verify_re_html, verify_re_latex): def verify_re_(rst, html_expected, latex_expected): if html_expected: verify_re_html(rst, html_expected) if latex_expected: verify_re_latex(rst, latex_expected) return verify_re_ @pytest.fixture def verify(verify_re_html, verify_re_latex): def verify_(rst, html_expected, latex_expected): if html_expected: verify_re_html(rst, re.escape(html_expected) + '$') if latex_expected: verify_re_latex(rst, re.escape(latex_expected) + '$') return verify_ @pytest.fixture def get_verifier(verify, verify_re): v = { 'verify': verify, 'verify_re': verify_re, } def get(name): return v[name] return get @pytest.mark.parametrize('type,rst,html_expected,latex_expected', [ ( # pep role 'verify_re', ':pep:`8`', # since docutils-0.19, :pep: role points to python.org via https schema ('
'), (r'\\sphinxAtStartPar\n' r'\\index{Python Enhancement Proposals@\\spxentry{Python Enhancement Proposals}' r'!PEP 8@\\spxentry{PEP 8}}\\sphinxhref{https?://www.python.org/dev/peps/pep-0008}' r'{\\sphinxstylestrong{PEP 8}}') ), ( # pep role with anchor 'verify_re', ':pep:`8#id1`', # since docutils-0.19, :pep: role points to python.org via https schema (''), (r'\\sphinxAtStartPar\n' r'\\index{Python Enhancement Proposals@\\spxentry{Python Enhancement Proposals}' r'!PEP 8\\#id1@\\spxentry{PEP 8\\#id1}}\\sphinxhref' r'{https?://www.python.org/dev/peps/pep-0008\\#id1}' r'{\\sphinxstylestrong{PEP 8\\#id1}}') ), ( # rfc role 'verify', ':rfc:`2324`', (''), ('\\sphinxAtStartPar\n' '\\index{RFC@\\spxentry{RFC}!RFC 2324@\\spxentry{RFC 2324}}' '\\sphinxhref{http://datatracker.ietf.org/doc/html/rfc2324.html}' '{\\sphinxstylestrong{RFC 2324}}') ), ( # rfc role with anchor 'verify', ':rfc:`2324#id1`', (''), ('\\sphinxAtStartPar\n' '\\index{RFC@\\spxentry{RFC}!RFC 2324\\#id1@\\spxentry{RFC 2324\\#id1}}' '\\sphinxhref{http://datatracker.ietf.org/doc/html/rfc2324.html\\#id1}' '{\\sphinxstylestrong{RFC 2324\\#id1}}') ), ( # correct interpretation of code with whitespace 'verify_re', '``code sample``', (''
'code sample
'), '\\sphinxAtStartPar\n\\sphinxmenuselection{a \\(\\rightarrow\\) b}', ), ( # interpolation of ampersands in menuselection 'verify', ':menuselection:`&Foo -&&- &Bar`', ('
'), ('\\sphinxAtStartPar\n' r'\sphinxmenuselection{\sphinxaccelerator{F}oo \sphinxhyphen{}' r'\&\sphinxhyphen{} \sphinxaccelerator{B}ar}'), ), ( # interpolation of ampersands in guilabel 'verify', ':guilabel:`&Foo -&&- &Bar`', ('
Foo ' '-&- Bar
'), ('\\sphinxAtStartPar\n' r'\sphinxguilabel{\sphinxaccelerator{F}oo \sphinxhyphen{}\&\sphinxhyphen{} \sphinxaccelerator{B}ar}'), ), ( # no ampersands in guilabel 'verify', ':guilabel:`Foo`', 'Foo
', '\\sphinxAtStartPar\n\\sphinxguilabel{Foo}', ), ( # kbd role 'verify', ':kbd:`space`', 'space
', '\\sphinxAtStartPar\n\\sphinxkeyboard{\\sphinxupquote{space}}', ), ( # kbd role 'verify', ':kbd:`Control+X`', ('' 'Control' '+' 'X' '
'), '\\sphinxAtStartPar\n\\sphinxkeyboard{\\sphinxupquote{Control+X}}', ), ( # kbd role 'verify', ':kbd:`Alt+^`', ('' 'Alt' '+' '^' '
'), ('\\sphinxAtStartPar\n' '\\sphinxkeyboard{\\sphinxupquote{Alt+\\textasciicircum{}}}'), ), ( # kbd role 'verify', ':kbd:`M-x M-s`', ('' 'M' '-' 'x' ' ' 'M' '-' 's' '
'), ('\\sphinxAtStartPar\n' '\\sphinxkeyboard{\\sphinxupquote{M\\sphinxhyphen{}x M\\sphinxhyphen{}s}}'), ), ( # kbd role 'verify', ':kbd:`-`', '-
', ('\\sphinxAtStartPar\n' '\\sphinxkeyboard{\\sphinxupquote{\\sphinxhyphen{}}}'), ), ( # kbd role 'verify', ':kbd:`Caps Lock`', 'Caps Lock
', ('\\sphinxAtStartPar\n' '\\sphinxkeyboard{\\sphinxupquote{Caps Lock}}'), ), ( # non-interpolation of dashes in option role 'verify_re', ':option:`--with-option`', (''
'--with-option
“John”
', "\\sphinxAtStartPar\n“John”", ), ( # ... but not in literal text 'verify', '``"John"``', (''
'"John"
mp(1)
', '\\sphinxAtStartPar\n\\sphinxstyleliteralemphasis{\\sphinxupquote{mp(1)}}', ), ( # correct escaping in normal mode 'verify', 'Γ\\\\∞$', None, '\\sphinxAtStartPar\nΓ\\textbackslash{}\\(\\infty\\)\\$', ), ( # in verbatim code fragments 'verify', '::\n\n @Γ\\∞${}', None, ('\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n' '@Γ\\PYGZbs{}\\(\\infty\\)\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n' '\\end{sphinxVerbatim}'), ), ( # in URIs 'verify_re', '`test4 backslashes \\
', None, ), ]) @pytest.mark.skipif(docutils.__version_info__ < (0, 16), reason='docutils-0.16 or above is required') def test_inline_docutils16(get_verifier, type, rst, html_expected, latex_expected): verifier = get_verifier(type) verifier(rst, html_expected, latex_expected) @pytest.mark.sphinx(confoverrides={'latex_engine': 'xelatex'}) @pytest.mark.parametrize('type,rst,html_expected,latex_expected', [ ( # in verbatim code fragments 'verify', '::\n\n @Γ\\∞${}', None, ('\\begin{sphinxVerbatim}[commandchars=\\\\\\{\\}]\n' '@Γ\\PYGZbs{}∞\\PYGZdl{}\\PYGZob{}\\PYGZcb{}\n' '\\end{sphinxVerbatim}'), ), ]) def test_inline_for_unicode_latex_engine(get_verifier, type, rst, html_expected, latex_expected): verifier = get_verifier(type) verifier(rst, html_expected, latex_expected) def test_samp_role(parse): # no braces text = ':samp:`a{b}c`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, nodes.literal, ("a", [nodes.emphasis, "b"], "c")]) # nested braces text = ':samp:`a{{b}}c`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, nodes.literal, ("a", [nodes.emphasis, "{b"], "}c")]) # half-opened braces text = ':samp:`a{bc`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, nodes.literal, "a{bc"]) # escaped braces text = ':samp:`a\\\\{b}c`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, nodes.literal, "a{b}c"]) # no braces (whitespaces are keeped as is) text = ':samp:`code sample`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, nodes.literal, "code sample"]) def test_download_role(parse): # implicit text = ':download:`sphinx.rst`' doctree = parse(text) assert_node(doctree[0], [nodes.paragraph, addnodes.download_reference, nodes.literal, "sphinx.rst"]) assert_node(doctree[0][0], refdoc='dummy', refdomain='', reftype='download', refexplicit=False, reftarget='sphinx.rst', refwarn=False) assert_node(doctree[0][0][0], classes=['xref', 'download']) # explicit text = ':download:`reftitle