def test_toctree_twice(app):
text = (".. toctree::\n"
"\n"
" foo\n"
" foo\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'foo'), (None, 'foo')],
includefiles=['foo', 'foo'])
def test_toctree_glob_and_url(app):
text = (".. toctree::\n"
" :glob:\n"
"\n"
" https://example.com/?q=sphinx\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'https://example.com/?q=sphinx')],
includefiles=[])
def assert_refnode(node, module_name, class_name, target, reftype=None,
domain='py'):
attributes = {
'refdomain': domain,
'reftarget': target,
}
if reftype is not None:
attributes['reftype'] = reftype
if module_name is not False:
attributes['py:module'] = module_name
if class_name is not False:
attributes['py:class'] = class_name
assert_node(node, **attributes)
def assert_refnode(node, mod_name, prefix, target, reftype=None,
domain='js'):
attributes = {
'refdomain': domain,
'reftarget': target,
}
if reftype is not None:
attributes['reftype'] = reftype
if mod_name is not False:
attributes['js:module'] = mod_name
if prefix is not False:
attributes['js:object'] = prefix
assert_node(node, **attributes)
def test_toctree_urls_and_titles(app):
text = (".. toctree::\n"
"\n"
" Sphinx <https://www.sphinx-doc.org/>\n"
" https://readthedocs.org/\n"
" The BAR <bar/index>\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[('Sphinx', 'https://www.sphinx-doc.org/'),
(None, 'https://readthedocs.org/'),
('The BAR', 'bar/index')],
includefiles=['bar/index'])
def test_relative_toctree(app):
text = (".. toctree::\n"
"\n"
" bar_1\n"
" bar_2\n"
" bar_3\n"
" ../quux\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'bar/index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'bar/bar_1'), (None, 'bar/bar_2'), (None, 'bar/bar_3'),
(None, 'quux')],
includefiles=['bar/bar_1', 'bar/bar_2', 'bar/bar_3', 'quux'])
def test_compact_refonly_bullet_list(app, status, warning):
app.builder.build_all()
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert len(doctree[0]) == 5
assert doctree[0][1].astext() == 'List A:'
assert_node(doctree[0][2], nodes.bullet_list)
assert_node(doctree[0][2][0][0], addnodes.compact_paragraph)
assert doctree[0][2][0][0].astext() == 'genindex'
assert doctree[0][3].astext() == 'List B:'
assert_node(doctree[0][4], nodes.bullet_list)
assert_node(doctree[0][4][0][0], nodes.paragraph)
assert doctree[0][4][0][0].astext() == 'Hello'
def test_get_toc_for(app):
app.build()
toctree = TocTree(app.env).get_toc_for('index', app.builder)
assert_node(toctree,
[bullet_list, ([list_item, (compact_paragraph, # [0][0]
[bullet_list, (addnodes.toctree, # [0][1][0]
comment, # [0][1][1]
list_item)])], # [0][1][2]
[list_item, (compact_paragraph, # [1][0]
[bullet_list, (addnodes.toctree,
addnodes.toctree)])],
[list_item, compact_paragraph])]) # [2][0]
assert_node(toctree[0][0],
[compact_paragraph, reference, u"Welcome to Sphinx Tests’s documentation!"])
assert_node(toctree[0][1][2],
([compact_paragraph, reference, "subsection"],
[bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
assert_node(toctree[1][0],
[compact_paragraph, reference, "Test for issue #1157"])
assert_node(toctree[2][0],
[compact_paragraph, reference, "Indices and tables"])
def test_get_toc_for_tocdepth(app):
app.build()
toctree = TocTree(app.env).get_toc_for('tocdepth', app.builder)
assert_node(toctree,
[bullet_list, list_item, (compact_paragraph, # [0][0]
bullet_list)]) # [0][1]
assert_node(toctree[0][0],
[compact_paragraph, reference, "level 1"])
assert_node(toctree[0][1],
[bullet_list, list_item, compact_paragraph, reference, "level 2"])
def test_math_compat(app, status, warning):
with warnings.catch_warnings(record=True):
app.builder.build_all()
doctree = app.env.get_and_resolve_doctree('index', app.builder)
assert_node(doctree,
[nodes.document, nodes.section, (nodes.title,
[nodes.section, (nodes.title,
nodes.paragraph)],
nodes.section)])
assert_node(doctree[0][1][1],
('Inline: ',
[nodes.math, "E=mc^2"],
'\nInline my math: ',
[nodes.math, "E = mc^2"]))
assert_node(doctree[0][2],
([nodes.title, "block"],
[nodes.math_block, "a^2+b^2=c^2\n\n"],
[nodes.paragraph, "Second math"],
[nodes.math_block, "e^{i\\pi}+1=0\n\n"],
[nodes.paragraph, "Multi math equations"],
[nodes.math_block, "E = mc^2"]))
def test_pyattribute(app):
text = (".. py:class:: Class\n"
"\n"
" .. py:attribute:: attr\n"
" :type: str\n"
" :value: ''\n")
domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, [
desc,
([desc_signature, ([desc_annotation, "class "], [desc_name, "Class"])
], [desc_content, (addnodes.index, desc)])
]))
assert_node(doctree[1][1][0],
addnodes.index,
entries=[('single', 'attr (Class attribute)', 'Class.attr', '',
None)])
assert_node(doctree[1][1][1], ([
desc_signature,
([desc_name, "attr"], [desc_annotation, ": str"
], [desc_annotation, " = ''"])
], [desc_content, ()]))
assert 'Class.attr' in domain.objects
assert domain.objects['Class.attr'] == ('index', 'attribute')
def test_glossary_comment2(app):
text = (".. glossary::\n"
"\n"
" term1\n"
" description\n"
"\n"
" .. term2\n"
" term3\n"
" description\n"
" description\n")
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (
[glossary, definition_list, ([definition_list_item, ([term, ("term1",
index)],
definition)],
[definition_list_item, ([term, ("term3",
index)],
definition)])],
))
assert_node(doctree[0][0][0][1],
[nodes.definition, nodes.paragraph, "description"])
assert_node(doctree[0][0][1][1],
[nodes.definition, nodes.paragraph, ("description\n"
"description")])
def test_keep_warnings_is_False(app, status, warning):
app.builder.build_all()
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert len(doctree[0]) == 1
def test_default_role1(app, status, warning):
app.builder.build_all()
# default-role: pep
doctree = app.env.get_doctree('index')
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], addnodes.index)
assert_node(doctree[0][1][1], nodes.target)
assert_node(doctree[0][1][2], nodes.reference, classes=["pep"])
# no default-role
doctree = app.env.get_doctree('foo')
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], nodes.title_reference)
assert_node(doctree[0][1][1], nodes.Text)
def test_image_glob_intl_using_figure_language_filename(app):
app.build()
# index.rst
doctree = app.env.get_doctree('index')
assert_node(doctree[0][1], nodes.image, uri='rimg.png.xx',
candidates={'*': 'rimg.png.xx'})
assert isinstance(doctree[0][2], nodes.figure)
assert_node(doctree[0][2][0], nodes.image, uri='rimg.png.xx',
candidates={'*': 'rimg.png.xx'})
assert_node(doctree[0][3], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
assert isinstance(doctree[0][4], nodes.figure)
assert_node(doctree[0][4][0], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
# subdir/index.rst
doctree = app.env.get_doctree('subdir/index')
assert_node(doctree[0][1], nodes.image, uri='subdir/rimg.png',
candidates={'*': 'subdir/rimg.png'})
assert_node(doctree[0][2], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.svg'})
assert isinstance(doctree[0][3], nodes.figure)
assert_node(doctree[0][3][0], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.svg'})
def test_process_doc(app):
app.build()
# tocs
toctree = app.env.tocs['index']
assert_node(toctree,
[bullet_list, ([list_item, (compact_paragraph, # [0][0]
[bullet_list, (addnodes.toctree, # [0][1][0]
only, # [0][1][1]
list_item)])], # [0][1][2]
[list_item, (compact_paragraph, # [1][0]
[bullet_list, (addnodes.toctree, # [1][1][0]
addnodes.toctree)])], # [1][1][1]
list_item)])
assert_node(toctree[0][0],
[compact_paragraph, reference, "Welcome to Sphinx Tests’s documentation!"])
assert_node(toctree[0][0][0], reference, anchorname='')
assert_node(toctree[0][1][0], addnodes.toctree,
caption="Table of Contents", glob=False, hidden=False,
titlesonly=False, maxdepth=2, numbered=999,
entries=[(None, 'foo'), (None, 'bar'), (None, 'http://sphinx-doc.org/')],
includefiles=['foo', 'bar'])
# only branch
assert_node(toctree[0][1][1], addnodes.only, expr="html")
assert_node(toctree[0][1][1],
[only, list_item, ([compact_paragraph, reference, "Section for HTML"],
[bullet_list, addnodes.toctree])])
assert_node(toctree[0][1][1][0][0][0], reference, anchorname='#section-for-html')
assert_node(toctree[0][1][1][0][1][0], addnodes.toctree,
caption=None, glob=False, hidden=False, entries=[(None, 'baz')],
includefiles=['baz'], titlesonly=False, maxdepth=-1, numbered=0)
assert_node(toctree[0][1][2],
([compact_paragraph, reference, "subsection"],
[bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
assert_node(toctree[1][0],
[compact_paragraph, reference, "Test for issue #1157"])
assert_node(toctree[1][0][0], reference, anchorname='#test-for-issue-1157')
assert_node(toctree[1][1][0], addnodes.toctree,
caption=None, entries=[], glob=False, hidden=False,
titlesonly=False, maxdepth=-1, numbered=0)
assert_node(toctree[1][1][1], addnodes.toctree,
caption=None, glob=False, hidden=True,
titlesonly=False, maxdepth=-1, numbered=0,
entries=[('Latest reference', 'http://sphinx-doc.org/latest/'),
('Python', 'http://python.org/')])
assert_node(toctree[2][0],
[compact_paragraph, reference, "Indices and tables"])
# other collections
assert app.env.toc_num_entries['index'] == 6
assert app.env.toctree_includes['index'] == ['foo', 'bar', 'baz']
assert app.env.files_to_rebuild['foo'] == {'index'}
assert app.env.files_to_rebuild['bar'] == {'index'}
assert app.env.files_to_rebuild['baz'] == {'index'}
assert app.env.glob_toctrees == set()
assert app.env.numbered_toctrees == {'index'}
# qux has no section title
assert len(app.env.tocs['qux']) == 0
assert_node(app.env.tocs['qux'], nodes.bullet_list)
assert app.env.toc_num_entries['qux'] == 0
assert 'qux' not in app.env.toctree_includes
def test_keep_warnings_is_True(app, status, warning):
app.builder.build_all()
doctree = app.env.get_doctree('index')
assert_node(doctree[0], nodes.section)
assert len(doctree[0]) == 2
assert_node(doctree[0][1], nodes.system_message)
def test_default_role2(app, status, warning):
app.builder.build_all()
# default-role directive is stronger than configratuion
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], addnodes.index)
assert_node(doctree[0][1][1], nodes.target)
assert_node(doctree[0][1][2], nodes.reference, classes=["pep"])
# default_role changes the default behavior
doctree = pickle.loads((app.doctreedir / 'foo.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], nodes.inline, classes=["guilabel"])
assert_node(doctree[0][1][1], nodes.Text)
def test_parse_annotation(app):
doctree = _parse_annotation("int", app.env)
assert_node(doctree, ([pending_xref, "int"], ))
assert_node(doctree[0],
pending_xref,
refdomain="py",
reftype="class",
reftarget="int")
doctree = _parse_annotation("List[int]", app.env)
assert_node(doctree, ([pending_xref, "List"], [desc_sig_punctuation, "["],
[pending_xref, "int"], [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("Tuple[int, int]", app.env)
assert_node(doctree, ([pending_xref, "Tuple"], [desc_sig_punctuation, "["],
[pending_xref, "int"], [desc_sig_punctuation, ", "],
[pending_xref, "int"], [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("Tuple[()]", app.env)
assert_node(doctree,
([pending_xref, "Tuple"], [desc_sig_punctuation, "["], [
desc_sig_punctuation, "("
], [desc_sig_punctuation, ")"], [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("Tuple[int, ...]", app.env)
assert_node(doctree,
([pending_xref, "Tuple"], [desc_sig_punctuation, "["],
[pending_xref, "int"], [desc_sig_punctuation, ", "],
[desc_sig_punctuation, "..."], [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("Callable[[int, int], int]", app.env)
assert_node(doctree,
([pending_xref, "Callable"], [desc_sig_punctuation, "["], [
desc_sig_punctuation, "["
], [pending_xref, "int"], [desc_sig_punctuation, ", "], [
pending_xref, "int"
], [desc_sig_punctuation, "]"], [desc_sig_punctuation, ", "],
[pending_xref, "int"], [desc_sig_punctuation, "]"]))
doctree = _parse_annotation("List[None]", app.env)
assert_node(doctree, ([pending_xref, "List"], [desc_sig_punctuation, "["],
[pending_xref, "None"], [desc_sig_punctuation, "]"]))
# None type makes an object-reference (not a class reference)
doctree = _parse_annotation("None", app.env)
assert_node(doctree, ([pending_xref, "None"], ))
assert_node(doctree[0],
pending_xref,
refdomain="py",
reftype="obj",
reftarget="None")
def test_get_toctree_for_maxdepth(app):
app.build()
toctree = app.env.get_toctree_for('index', app.builder, collapse=False, maxdepth=3)
assert_node(toctree,
[compact_paragraph, ([caption, "Table of Contents"],
bullet_list,
bullet_list,
bullet_list)])
assert_node(toctree[1],
([list_item, ([compact_paragraph, reference, "foo"],
bullet_list)],
[list_item, compact_paragraph, reference, "bar"],
[list_item, compact_paragraph, reference, "http://sphinx-doc.org/"]))
assert_node(toctree[1][0][1],
([list_item, compact_paragraph, reference, "quux"],
[list_item, ([compact_paragraph, reference, "foo.1"],
bullet_list)],
[list_item, compact_paragraph, reference, "foo.2"]))
assert_node(toctree[1][0][1][1][1],
[bullet_list, list_item, compact_paragraph, reference, "foo.1-1"])
assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=(1,))
assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=(1, 1))
assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=(1, 2))
assert_node(toctree[1][0][1][1][1][0][0][0],
reference, refuri="foo#foo-1-1", secnumber=(1, 2, 1))
assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=(1, 3))
assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=(2,))
assert_node(toctree[1][2][0][0], reference, refuri="http://sphinx-doc.org/")
assert_node(toctree[2],
[bullet_list, list_item, compact_paragraph, reference, "baz"])
assert_node(toctree[3],
([list_item, compact_paragraph, reference, "Latest reference"],
[list_item, compact_paragraph, reference, "Python"]))
assert_node(toctree[3][0][0][0], reference, refuri="http://sphinx-doc.org/latest/")
assert_node(toctree[3][1][0][0], reference, refuri="http://python.org/")
def test_image_glob_intl(app):
app.build()
# index.rst
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0][1], nodes.image, uri='rimg.xx.png',
candidates={'*': 'rimg.xx.png'})
assert isinstance(doctree[0][2], nodes.figure)
assert_node(doctree[0][2][0], nodes.image, uri='rimg.xx.png',
candidates={'*': 'rimg.xx.png'})
assert_node(doctree[0][3], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
assert isinstance(doctree[0][4], nodes.figure)
assert_node(doctree[0][4][0], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
# subdir/index.rst
doctree = pickle.loads((app.doctreedir / 'subdir/index.doctree').bytes())
assert_node(doctree[0][1], nodes.image, uri='subdir/rimg.xx.png',
candidates={'*': 'subdir/rimg.xx.png'})
assert_node(doctree[0][2], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.xx.svg'})
assert isinstance(doctree[0][3], nodes.figure)
assert_node(doctree[0][3][0], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.xx.svg'})
def test_toctree_glob(app):
text = (".. toctree::\n" " :glob:\n" "\n" " *\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux')],
includefiles=['baz', 'foo', 'quux'])
# give both docname and glob (case1)
text = (".. toctree::\n" " :glob:\n" "\n" " foo\n" " *\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'foo'), (None, 'baz'), (None, 'quux')],
includefiles=['foo', 'baz', 'quux'])
# give both docname and glob (case2)
text = (".. toctree::\n" " :glob:\n" "\n" " *\n" " foo\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux'),
(None, 'foo')],
includefiles=['baz', 'foo', 'quux', 'foo'])
def test_productionlist2(app):
text = (".. productionlist:: P2\n"
" A: `:A` `A`\n"
" B: `P1:B` `~P1:B`\n")
doctree = restructuredtext.parse(app, text)
refnodes = list(doctree.traverse(pending_xref))
assert_node(refnodes[0], pending_xref, reftarget="A")
assert_node(refnodes[1], pending_xref, reftarget="P2:A")
assert_node(refnodes[2], pending_xref, reftarget="P1:B")
assert_node(refnodes[3], pending_xref, reftarget="P1:B")
assert_node(refnodes[0], [pending_xref, nodes.literal, "A"])
assert_node(refnodes[1], [pending_xref, nodes.literal, "A"])
assert_node(refnodes[2], [pending_xref, nodes.literal, "P1:B"])
assert_node(refnodes[3], [pending_xref, nodes.literal, "B"])
def test_glob(app):
includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
'bar/bar_3', 'baz', 'qux/index']
app.build()
# tocs
toctree = app.env.tocs['index']
assert_node(toctree,
[bullet_list, list_item, (compact_paragraph, # [0][0]
[bullet_list, (list_item, # [0][1][0]
list_item)])]) # [0][1][1]
assert_node(toctree[0][0],
[compact_paragraph, reference, "test-toctree-glob"])
assert_node(toctree[0][1][0],
[list_item, ([compact_paragraph, reference, "normal order"],
[bullet_list, addnodes.toctree])]) # [0][1][0][1][0]
assert_node(toctree[0][1][0][1][0], addnodes.toctree, caption=None,
glob=True, hidden=False, titlesonly=False,
maxdepth=-1, numbered=0, includefiles=includefiles,
entries=[(None, 'foo'), (None, 'bar/index'), (None, 'bar/bar_1'),
(None, 'bar/bar_2'), (None, 'bar/bar_3'), (None, 'baz'),
(None, 'qux/index'),
('hyperref', 'https://sphinx-doc.org/?q=sphinx')])
assert_node(toctree[0][1][1],
[list_item, ([compact_paragraph, reference, "reversed order"],
[bullet_list, addnodes.toctree])]) # [0][1][1][1][0]
assert_node(toctree[0][1][1][1][0], addnodes.toctree, caption=None,
glob=True, hidden=False, titlesonly=False,
maxdepth=-1, numbered=0, includefiles=includefiles,
entries=[(None, 'qux/index'), (None, 'baz'), (None, 'bar/bar_3'),
(None, 'bar/bar_2'), (None, 'bar/bar_1'), (None, 'bar/index'),
(None, 'foo')])
includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
'bar/bar_3', 'baz', 'qux/index']
# other collections
assert app.env.toc_num_entries['index'] == 3
assert app.env.toctree_includes['index'] == includefiles + includefiles
for file in includefiles:
assert 'index' in app.env.files_to_rebuild[file]
assert 'index' in app.env.glob_toctrees
assert app.env.numbered_toctrees == set()
def test_get_toctree_for_includehidden(app):
app.build()
toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=False,
includehidden=False)
assert_node(toctree,
[compact_paragraph, ([caption, "Table of Contents"],
bullet_list,
bullet_list)])
assert_node(toctree[1],
([list_item, ([compact_paragraph, reference, "foo"],
bullet_list)],
[list_item, compact_paragraph, reference, "bar"],
[list_item, compact_paragraph, reference, "http://sphinx-doc.org/"]))
assert_node(toctree[1][0][1],
([list_item, compact_paragraph, reference, "quux"],
[list_item, compact_paragraph, reference, "foo.1"],
[list_item, compact_paragraph, reference, "foo.2"]))
assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=[1, 1])
assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=[1, 2])
assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=[1, 3])
assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
assert_node(toctree[1][2][0][0], reference, refuri="http://sphinx-doc.org/")
assert_node(toctree[2],
[bullet_list, list_item, compact_paragraph, reference, "baz"])
def test_get_toctree_for_collapse(app):
app.build()
toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=True)
assert_node(toctree,
[compact_paragraph, ([caption, "Table of Contents"],
bullet_list,
bullet_list,
bullet_list)])
assert_node(toctree[1],
([list_item, compact_paragraph, reference, "foo"],
[list_item, compact_paragraph, reference, "bar"],
[list_item, compact_paragraph, reference, "http://sphinx-doc.org/"]))
assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
assert_node(toctree[1][2][0][0], reference, refuri="http://sphinx-doc.org/")
assert_node(toctree[2],
[bullet_list, list_item, compact_paragraph, reference, "baz"])
assert_node(toctree[3],
([list_item, compact_paragraph, reference, "Latest reference"],
[list_item, compact_paragraph, reference, "Python"]))
assert_node(toctree[3][0][0][0], reference, refuri="http://sphinx-doc.org/latest/")
assert_node(toctree[3][1][0][0], reference, refuri="http://python.org/")
def test_get_toc_for_only(app):
app.build()
builder = StandaloneHTMLBuilder(app)
toctree = app.env.get_toc_for('index', builder)
assert_node(toctree,
[bullet_list, ([list_item, (compact_paragraph, # [0][0]
[bullet_list, (addnodes.toctree, # [0][1][0]
list_item, # [0][1][1]
list_item)])], # [0][1][2]
[list_item, (compact_paragraph, # [1][0]
[bullet_list, (addnodes.toctree,
addnodes.toctree)])],
[list_item, compact_paragraph])]) # [2][0]
assert_node(toctree[0][0],
[compact_paragraph, reference, u"Welcome to Sphinx Tests’s documentation!"])
assert_node(toctree[0][1][1],
([compact_paragraph, reference, "Section for HTML"],
[bullet_list, addnodes.toctree]))
assert_node(toctree[0][1][2],
([compact_paragraph, reference, "subsection"],
[bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
assert_node(toctree[1][0],
[compact_paragraph, reference, "Test for issue #1157"])
assert_node(toctree[2][0],
[compact_paragraph, reference, "Indices and tables"])
def test_samp():
# normal case
text = 'print 1+{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, ("print 1+",
[nodes.emphasis, "variable"])],))
assert msg == []
# two emphasis items
text = 'print {1}+{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, ("print ",
[nodes.emphasis, "1"],
"+",
[nodes.emphasis, "variable"])],))
assert msg == []
# empty curly brace
text = 'print 1+{}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, "print 1+{}"],))
assert msg == []
# half-opened variable
text = 'print 1+{variable'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, "print 1+{variable"],))
assert msg == []
# nested
text = 'print 1+{{variable}}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, ("print 1+",
[nodes.emphasis, "{variable"],
"}")],))
assert msg == []
# emphasized item only
text = '{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, nodes.emphasis, "variable"],))
assert msg == []
# escaping
text = r'print 1+\{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, "print 1+{variable}"],))
assert msg == []
# escaping (2)
text = r'print 1+\{{variable}\}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, ("print 1+{",
[nodes.emphasis, "variable"],
"}")],))
assert msg == []
# escape a backslash
text = r'print 1+\\{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret, ([nodes.literal, ("print 1+\\",
[nodes.emphasis, "variable"])],))
assert msg == []
def test_default_role1(app, status, warning):
app.builder.build_all()
# default-role: pep
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], addnodes.index)
assert_node(doctree[0][1][1], nodes.target)
assert_node(doctree[0][1][2], nodes.reference, classes=["pep"])
# no default-role
doctree = pickle.loads((app.doctreedir / 'foo.doctree').bytes())
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], nodes.title_reference)
assert_node(doctree[0][1][1], nodes.Text)
def test_autosummary_generate(app, status, warning):
app.builder.build_all()
doctree = app.env.get_doctree('index')
assert_node(doctree,
(nodes.paragraph, nodes.paragraph, addnodes.tabular_col_spec,
autosummary_table, [autosummary_toc, addnodes.toctree]))
assert_node(doctree[3], [
autosummary_table, nodes.table, nodes.tgroup,
(nodes.colspec, nodes.colspec, [
nodes.tbody,
(nodes.row, nodes.row, nodes.row, nodes.row, nodes.row, nodes.row)
])
])
assert_node(doctree[4][0], addnodes.toctree, caption="An autosummary")
assert len(doctree[3][0][0][2]) == 6
assert doctree[3][0][0][2][0].astext() == 'autosummary_dummy_module\n\n'
assert doctree[3][0][0][2][1].astext(
) == 'autosummary_dummy_module.Foo()\n\n'
assert doctree[3][0][0][2][2].astext(
) == 'autosummary_dummy_module.Foo.Bar()\n\n'
assert doctree[3][0][0][2][3].astext(
) == 'autosummary_dummy_module.Foo.value\n\ndocstring'
assert doctree[3][0][0][2][4].astext(
) == 'autosummary_dummy_module.bar(x[, y])\n\n'
assert doctree[3][0][0][2][5].astext(
) == 'autosummary_dummy_module.qux\n\na module-level attribute'
module = (app.srcdir / 'generated' /
'autosummary_dummy_module.rst').read_text()
assert (' .. autosummary::\n' ' \n' ' Foo\n' ' \n' in module)
assert (' .. autosummary::\n'
' \n'
' CONSTANT1\n'
' qux\n'
' \n' in module)
Foo = (app.srcdir / 'generated' /
'autosummary_dummy_module.Foo.rst').read_text()
assert '.. automethod:: __init__' in Foo
assert (' .. autosummary::\n'
' \n'
' ~Foo.__init__\n'
' ~Foo.bar\n'
' \n' in Foo)
assert (' .. autosummary::\n'
' \n'
' ~Foo.CONSTANT3\n'
' ~Foo.CONSTANT4\n'
' ~Foo.baz\n'
' \n' in Foo)
FooBar = (app.srcdir / 'generated' /
'autosummary_dummy_module.Foo.Bar.rst').read_text()
assert ('.. currentmodule:: autosummary_dummy_module\n'
'\n'
'.. autoclass:: Foo.Bar\n' in FooBar)
Foo_value = (app.srcdir / 'generated' /
'autosummary_dummy_module.Foo.value.rst').read_text()
assert ('.. currentmodule:: autosummary_dummy_module\n'
'\n'
'.. autoattribute:: Foo.value' in Foo_value)
qux = (app.srcdir / 'generated' /
'autosummary_dummy_module.qux.rst').read_text()
assert ('.. currentmodule:: autosummary_dummy_module\n'
'\n'
'.. autodata:: qux' in qux)
def test_glossary(app):
text = (".. glossary::\n"
"\n"
" term1\n"
" TERM2\n"
" description\n"
"\n"
" term3 : classifier\n"
" description\n"
" description\n"
"\n"
" term4 : class1 : class2\n"
" description\n")
# doctree
doctree = restructuredtext.parse(app, text)
assert_node(doctree, ([
glossary, definition_list,
([
definition_list_item,
([term, ("term1", index)], [term, ("TERM2", index)], definition)
], [definition_list_item, ([term, ("term3", index)], definition)
], [definition_list_item, ([term, ("term4", index)], definition)])
], ))
assert_node(doctree[0][0][0][0][1],
entries=[("single", "term1", "term-term1", "main", None)])
assert_node(doctree[0][0][0][1][1],
entries=[("single", "TERM2", "term-TERM2", "main", None)])
assert_node(doctree[0][0][0][2],
[definition, nodes.paragraph, "description"])
assert_node(doctree[0][0][1][0][1],
entries=[("single", "term3", "term-term3", "main",
"classifier")])
assert_node(doctree[0][0][1][1],
[definition, nodes.paragraph, ("description\n"
"description")])
assert_node(doctree[0][0][2][0][1],
entries=[("single", "term4", "term-term4", "main", "class1")])
assert_node(doctree[0][0][2][1],
[nodes.definition, nodes.paragraph, "description"])
# index
domain = app.env.get_domain("std")
objects = list(domain.get_objects())
assert ("term1", "term1", "term", "index", "term-term1", -1) in objects
assert ("TERM2", "TERM2", "term", "index", "term-TERM2", -1) in objects
assert ("term3", "term3", "term", "index", "term-term3", -1) in objects
assert ("term4", "term4", "term", "index", "term-term4", -1) in objects
# term reference (case sensitive)
refnode = domain.resolve_xref(app.env, 'index', app.builder, 'term',
'term1', pending_xref(), nodes.paragraph())
assert_node(refnode, nodes.reference, refid="term-term1")
# term reference (case insensitive)
refnode = domain.resolve_xref(app.env, 'index', app.builder, 'term',
'term2', pending_xref(), nodes.paragraph())
assert_node(refnode, nodes.reference, refid="term-TERM2")
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 <sphinx.rst>`'
doctree = parse(text)
assert_node(doctree[0], [
nodes.paragraph, addnodes.download_reference, nodes.literal, "reftitle"
])
assert_node(doctree[0][0],
refdoc='dummy',
refdomain='',
reftype='download',
refexplicit=True,
reftarget='sphinx.rst',
refwarn=False)
assert_node(doctree[0][0][0], classes=['xref', 'download'])
def test_noindexentry(app):
text = (".. py:function:: f()\n"
".. py:function:: g()\n"
" :noindexentry:\n")
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, desc, addnodes.index, desc))
assert_node(doctree[0],
addnodes.index,
entries=[('pair', 'built-in function; f()', 'f', '', None)])
assert_node(doctree[2], addnodes.index, entries=[])
text = (".. py:class:: f\n" ".. py:class:: g\n" " :noindexentry:\n")
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, desc, addnodes.index, desc))
assert_node(doctree[0],
addnodes.index,
entries=[('single', 'f (built-in class)', 'f', '', None)])
assert_node(doctree[2], addnodes.index, entries=[])
def test_get_toc_for_only(app):
app.build()
builder = StandaloneHTMLBuilder(app)
toctree = TocTree(app.env).get_toc_for('index', builder)
assert_node(toctree,
[bullet_list, ([list_item, (compact_paragraph, # [0][0]
[bullet_list, (addnodes.toctree, # [0][1][0]
list_item, # [0][1][1]
list_item)])], # [0][1][2]
[list_item, (compact_paragraph, # [1][0]
[bullet_list, (addnodes.toctree,
addnodes.toctree)])],
[list_item, compact_paragraph])]) # [2][0]
assert_node(toctree[0][0],
[compact_paragraph, reference, "Welcome to Sphinx Tests’s documentation!"])
assert_node(toctree[0][1][1],
([compact_paragraph, reference, "Section for HTML"],
[bullet_list, addnodes.toctree]))
assert_node(toctree[0][1][2],
([compact_paragraph, reference, "subsection"],
[bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
assert_node(toctree[1][0],
[compact_paragraph, reference, "Test for issue #1157"])
assert_node(toctree[2][0],
[compact_paragraph, reference, "Indices and tables"])
def test_image_glob_intl_using_figure_language_filename(app):
app.build()
# index.rst
doctree = pickle.loads((app.doctreedir / 'index.doctree').bytes())
assert_node(doctree[0][1], nodes.image, uri='rimg.png.xx',
candidates={'*': 'rimg.png.xx'})
assert isinstance(doctree[0][2], nodes.figure)
assert_node(doctree[0][2][0], nodes.image, uri='rimg.png.xx',
candidates={'*': 'rimg.png.xx'})
assert_node(doctree[0][3], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
assert isinstance(doctree[0][4], nodes.figure)
assert_node(doctree[0][4][0], nodes.image, uri='img.*',
candidates={'application/pdf': 'img.pdf',
'image/gif': 'img.gif',
'image/png': 'img.png'})
# subdir/index.rst
doctree = pickle.loads((app.doctreedir / 'subdir/index.doctree').bytes())
assert_node(doctree[0][1], nodes.image, uri='subdir/rimg.png',
candidates={'*': 'subdir/rimg.png'})
assert_node(doctree[0][2], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.svg'})
assert isinstance(doctree[0][3], nodes.figure)
assert_node(doctree[0][3][0], nodes.image, uri='subdir/svgimg.*',
candidates={'application/pdf': 'subdir/svgimg.pdf',
'image/svg+xml': 'subdir/svgimg.svg'})
def test_process_doc(app):
app.build()
# tocs
toctree = app.env.tocs['index']
assert_node(toctree,
[bullet_list, ([list_item, (compact_paragraph, # [0][0]
[bullet_list, (addnodes.toctree, # [0][1][0]
only, # [0][1][1]
list_item)])], # [0][1][2]
[list_item, (compact_paragraph, # [1][0]
[bullet_list, (addnodes.toctree, # [1][1][0]
addnodes.toctree)])], # [1][1][1]
list_item)])
assert_node(toctree[0][0],
[compact_paragraph, reference, u"Welcome to Sphinx Tests’s documentation!"])
assert_node(toctree[0][0][0], reference, anchorname='')
assert_node(toctree[0][1][0], addnodes.toctree,
caption="Table of Contents", glob=False, hidden=False,
titlesonly=False, maxdepth=2, numbered=999,
entries=[(None, 'foo'), (None, 'bar'), (None, 'http://sphinx-doc.org/')],
includefiles=['foo', 'bar'])
# only branch
assert_node(toctree[0][1][1], addnodes.only, expr="html")
assert_node(toctree[0][1][1],
[only, list_item, ([compact_paragraph, reference, "Section for HTML"],
[bullet_list, addnodes.toctree])])
assert_node(toctree[0][1][1][0][0][0], reference, anchorname='#section-for-html')
assert_node(toctree[0][1][1][0][1][0], addnodes.toctree,
caption=None, glob=False, hidden=False, entries=[(None, 'baz')],
includefiles=['baz'], titlesonly=False, maxdepth=-1, numbered=0)
assert_node(toctree[0][1][2],
([compact_paragraph, reference, "subsection"],
[bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
assert_node(toctree[1][0],
[compact_paragraph, reference, "Test for issue #1157"])
assert_node(toctree[1][0][0], reference, anchorname='#test-for-issue-1157')
assert_node(toctree[1][1][0], addnodes.toctree,
caption=None, entries=[], glob=False, hidden=False,
titlesonly=False, maxdepth=-1, numbered=0)
assert_node(toctree[1][1][1], addnodes.toctree,
caption=None, glob=False, hidden=True,
titlesonly=False, maxdepth=-1, numbered=0,
entries=[('Latest reference', 'http://sphinx-doc.org/latest/'),
('Python', 'http://python.org/')])
assert_node(toctree[2][0],
[compact_paragraph, reference, "Indices and tables"])
# other collections
assert app.env.toc_num_entries['index'] == 6
assert app.env.toctree_includes['index'] == ['foo', 'bar', 'baz']
assert app.env.files_to_rebuild['foo'] == set(['index'])
assert app.env.files_to_rebuild['bar'] == set(['index'])
assert app.env.files_to_rebuild['baz'] == set(['index'])
assert app.env.glob_toctrees == set()
assert app.env.numbered_toctrees == set(['index'])
# qux has no section title
assert len(app.env.tocs['qux']) == 0
assert_node(app.env.tocs['qux'], nodes.bullet_list)
assert app.env.toc_num_entries['qux'] == 0
assert 'qux' not in app.env.toctree_includes
def test_pymethod_options(app):
text = (".. py:class:: Class\n"
"\n"
" .. py:method:: meth1\n"
" .. py:method:: meth2\n"
" :classmethod:\n"
" .. py:method:: meth3\n"
" :staticmethod:\n"
" .. py:method:: meth4\n"
" :async:\n"
" .. py:method:: meth5\n"
" :property:\n"
" .. py:method:: meth6\n"
" :abstractmethod:\n")
domain = app.env.get_domain('py')
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "],
[desc_name, "Class"])],
[desc_content, (addnodes.index,
desc,
addnodes.index,
desc,
addnodes.index,
desc,
addnodes.index,
desc,
addnodes.index,
desc,
addnodes.index,
desc)])]))
# method
assert_node(doctree[1][1][0], addnodes.index,
entries=[('single', 'meth1() (Class method)', 'Class.meth1', '', None)])
assert_node(doctree[1][1][1], ([desc_signature, ([desc_name, "meth1"],
[desc_parameterlist, ()])],
[desc_content, ()]))
assert 'Class.meth1' in domain.objects
assert domain.objects['Class.meth1'] == ('index', 'method')
# :classmethod:
assert_node(doctree[1][1][2], addnodes.index,
entries=[('single', 'meth2() (Class class method)', 'Class.meth2', '', None)])
assert_node(doctree[1][1][3], ([desc_signature, ([desc_annotation, "classmethod "],
[desc_name, "meth2"],
[desc_parameterlist, ()])],
[desc_content, ()]))
assert 'Class.meth2' in domain.objects
assert domain.objects['Class.meth2'] == ('index', 'method')
# :staticmethod:
assert_node(doctree[1][1][4], addnodes.index,
entries=[('single', 'meth3() (Class static method)', 'Class.meth3', '', None)])
assert_node(doctree[1][1][5], ([desc_signature, ([desc_annotation, "static "],
[desc_name, "meth3"],
[desc_parameterlist, ()])],
[desc_content, ()]))
assert 'Class.meth3' in domain.objects
assert domain.objects['Class.meth3'] == ('index', 'method')
# :async:
assert_node(doctree[1][1][6], addnodes.index,
entries=[('single', 'meth4() (Class method)', 'Class.meth4', '', None)])
assert_node(doctree[1][1][7], ([desc_signature, ([desc_annotation, "async "],
[desc_name, "meth4"],
[desc_parameterlist, ()])],
[desc_content, ()]))
assert 'Class.meth4' in domain.objects
assert domain.objects['Class.meth4'] == ('index', 'method')
# :property:
assert_node(doctree[1][1][8], addnodes.index,
entries=[('single', 'meth5() (Class property)', 'Class.meth5', '', None)])
assert_node(doctree[1][1][9], ([desc_signature, ([desc_annotation, "property "],
[desc_name, "meth5"])],
[desc_content, ()]))
assert 'Class.meth5' in domain.objects
assert domain.objects['Class.meth5'] == ('index', 'method')
# :abstractmethod:
assert_node(doctree[1][1][10], addnodes.index,
entries=[('single', 'meth6() (Class method)', 'Class.meth6', '', None)])
assert_node(doctree[1][1][11], ([desc_signature, ([desc_annotation, "abstract "],
[desc_name, "meth6"],
[desc_parameterlist, ()])],
[desc_content, ()]))
assert 'Class.meth6' in domain.objects
assert domain.objects['Class.meth6'] == ('index', 'method')
def test_get_toctree_for_collapse(app):
app.build()
toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=True)
assert_node(toctree,
[compact_paragraph, ([caption, "Table of Contents"],
bullet_list,
bullet_list,
bullet_list)])
assert_node(toctree[1],
([list_item, compact_paragraph, reference, "foo"],
[list_item, compact_paragraph, reference, "bar"],
[list_item, compact_paragraph, reference, "http://sphinx-doc.org/"]))
assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=(1,))
assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=(2,))
assert_node(toctree[1][2][0][0], reference, refuri="http://sphinx-doc.org/")
assert_node(toctree[2],
[bullet_list, list_item, compact_paragraph, reference, "baz"])
assert_node(toctree[3],
([list_item, compact_paragraph, reference, "Latest reference"],
[list_item, compact_paragraph, reference, "Python"]))
assert_node(toctree[3][0][0][0], reference, refuri="http://sphinx-doc.org/latest/")
assert_node(toctree[3][1][0][0], reference, refuri="http://python.org/")
def test_rst_directive(app):
# bare
text = ".. rst:directive:: toctree"
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, [
desc, ([desc_signature, desc_name, ".. toctree::"], [desc_content, ()])
]))
assert_node(doctree[0],
entries=[("single", "toctree (directive)", "directive-toctree",
"", None)])
assert_node(doctree[1],
addnodes.desc,
desctype="directive",
domain="rst",
objtype="directive",
noindex=False)
# decorated
text = ".. rst:directive:: .. toctree::"
doctree = restructuredtext.parse(app, text)
assert_node(doctree, (addnodes.index, [
desc, ([desc_signature, desc_name, ".. toctree::"], [desc_content, ()])
]))
assert_node(doctree[0],
entries=[("single", "toctree (directive)", "directive-toctree",
"", None)])
assert_node(doctree[1],
addnodes.desc,
desctype="directive",
domain="rst",
objtype="directive",
noindex=False)
def test_get_toctree_for_includehidden(app):
app.build()
toctree = TocTree(app.env).get_toctree_for('index', app.builder, collapse=False,
includehidden=False)
assert_node(toctree,
[compact_paragraph, ([caption, "Table of Contents"],
bullet_list,
bullet_list)])
assert_node(toctree[1],
([list_item, ([compact_paragraph, reference, "foo"],
bullet_list)],
[list_item, compact_paragraph, reference, "bar"],
[list_item, compact_paragraph, reference, "http://sphinx-doc.org/"]))
assert_node(toctree[1][0][1],
([list_item, compact_paragraph, reference, "quux"],
[list_item, compact_paragraph, reference, "foo.1"],
[list_item, compact_paragraph, reference, "foo.2"]))
assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=(1,))
assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=(1, 1))
assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=(1, 2))
assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=(1, 3))
assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=(2,))
assert_node(toctree[1][2][0][0], reference, refuri="http://sphinx-doc.org/")
assert_node(toctree[2],
[bullet_list, list_item, compact_paragraph, reference, "baz"])
def test_XRefRole(inliner):
role = XRefRole()
# implicit
doctrees, errors = role('ref', 'rawtext', 'text', 5, inliner, {}, [])
assert len(doctrees) == 1
assert_node(doctrees[0], [addnodes.pending_xref, nodes.literal, 'text'])
assert_node(doctrees[0],
refdoc='dummy',
refdomain='',
reftype='ref',
reftarget='text',
refexplicit=False,
refwarn=False)
assert errors == []
# explicit
doctrees, errors = role('ref', 'rawtext', 'title <target>', 5, inliner, {},
[])
assert_node(doctrees[0], [addnodes.pending_xref, nodes.literal, 'title'])
assert_node(doctrees[0],
refdoc='dummy',
refdomain='',
reftype='ref',
reftarget='target',
refexplicit=True,
refwarn=False)
# bang
doctrees, errors = role('ref', 'rawtext', '!title <target>', 5, inliner,
{}, [])
assert_node(doctrees[0], [nodes.literal, 'title <target>'])
# refdomain
doctrees, errors = role('test:doc', 'rawtext', 'text', 5, inliner, {}, [])
assert_node(doctrees[0], [addnodes.pending_xref, nodes.literal, 'text'])
assert_node(doctrees[0],
refdoc='dummy',
refdomain='test',
reftype='doc',
reftarget='text',
refexplicit=False,
refwarn=False)
# fix_parens
role = XRefRole(fix_parens=True)
doctrees, errors = role('ref', 'rawtext', 'text()', 5, inliner, {}, [])
assert_node(doctrees[0], [addnodes.pending_xref, nodes.literal, 'text()'])
assert_node(doctrees[0],
refdoc='dummy',
refdomain='',
reftype='ref',
reftarget='text',
refexplicit=False,
refwarn=False)
# lowercase
role = XRefRole(lowercase=True)
doctrees, errors = role('ref', 'rawtext', 'TEXT', 5, inliner, {}, [])
assert_node(doctrees[0], [addnodes.pending_xref, nodes.literal, 'TEXT'])
assert_node(doctrees[0],
refdoc='dummy',
refdomain='',
reftype='ref',
reftarget='text',
refexplicit=False,
refwarn=False)
def test_glob(app):
includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
'bar/bar_3', 'baz', 'qux/index']
app.build()
# tocs
toctree = app.env.tocs['index']
assert_node(toctree,
[bullet_list, list_item, (compact_paragraph, # [0][0]
[bullet_list, (list_item, # [0][1][0]
list_item)])]) # [0][1][1]
assert_node(toctree[0][0],
[compact_paragraph, reference, "test-toctree-glob"])
assert_node(toctree[0][1][0],
[list_item, ([compact_paragraph, reference, "normal order"],
[bullet_list, addnodes.toctree])]) # [0][1][0][1][0]
assert_node(toctree[0][1][0][1][0], addnodes.toctree, caption=None,
glob=True, hidden=False, titlesonly=False,
maxdepth=-1, numbered=0, includefiles=includefiles,
entries=[(None, 'foo'), (None, 'bar/index'), (None, 'bar/bar_1'),
(None, 'bar/bar_2'), (None, 'bar/bar_3'), (None, 'baz'),
(None, 'qux/index'), ('hyperref', 'https://sphinx-doc.org/?q=sphinx')])
assert_node(toctree[0][1][1],
[list_item, ([compact_paragraph, reference, "reversed order"],
[bullet_list, addnodes.toctree])]) # [0][1][1][1][0]
assert_node(toctree[0][1][1][1][0], addnodes.toctree, caption=None,
glob=True, hidden=False, titlesonly=False,
maxdepth=-1, numbered=0, includefiles=includefiles,
entries=[(None, 'qux/index'), (None, 'baz'), (None, 'bar/bar_3'),
(None, 'bar/bar_2'), (None, 'bar/bar_1'), (None, 'bar/index'),
(None, 'foo')])
includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
'bar/bar_3', 'baz', 'qux/index']
# other collections
assert app.env.toc_num_entries['index'] == 3
assert app.env.toctree_includes['index'] == includefiles + includefiles
for file in includefiles:
assert 'index' in app.env.files_to_rebuild[file]
assert 'index' in app.env.glob_toctrees
assert app.env.numbered_toctrees == set()
def test_keep_warnings_is_False(app, status, warning):
app.builder.build_all()
doctree = app.env.get_doctree('index')
assert_node(doctree[0], nodes.section)
assert len(doctree[0]) == 1
def test_toctree_glob(app):
text = (".. toctree::\n"
" :glob:\n"
"\n"
" *\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux')],
includefiles=['baz', 'foo', 'quux'])
# give both docname and glob (case1)
text = (".. toctree::\n"
" :glob:\n"
"\n"
" foo\n"
" *\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'foo'), (None, 'baz'), (None, 'quux')],
includefiles=['foo', 'baz', 'quux'])
# give both docname and glob (case2)
text = (".. toctree::\n"
" :glob:\n"
"\n"
" *\n"
" foo\n")
app.env.find_files(app.config, app.builder)
doctree = parse(app, 'index', text)
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
assert_node(doctree[0][0],
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux'), (None, 'foo')],
includefiles=['baz', 'foo', 'quux', 'foo'])
def test_default_role2(app, status, warning):
app.builder.build_all()
# default-role directive is stronger than configratuion
doctree = app.env.get_doctree('index')
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], addnodes.index)
assert_node(doctree[0][1][1], nodes.target)
assert_node(doctree[0][1][2], nodes.reference, classes=["pep"])
# default_role changes the default behavior
doctree = app.env.get_doctree('foo')
assert_node(doctree[0], nodes.section)
assert_node(doctree[0][1], nodes.paragraph)
assert_node(doctree[0][1][0], nodes.inline, classes=["guilabel"])
assert_node(doctree[0][1][1], nodes.Text)
def test_math_directive(app):
# normal case
text = '.. math:: E = mc^2'
doctree = restructuredtext.parse(app, text)
assert_node(doctree, [nodes.document, nodes.math_block, 'E = mc^2\n\n'])
# :name: option
text = ('.. math:: E = mc^2\n' ' :name: eq1\n')
doctree = restructuredtext.parse(app, text)
assert_node(
doctree,
[nodes.document, (nodes.target, [nodes.math_block, "E = mc^2\n\n"])])
assert_node(doctree[1],
nodes.math_block,
docname='index',
label="eq1",
number=1)
# :label: option
text = ('.. math:: E = mc^2\n' ' :label: eq2\n')
doctree = restructuredtext.parse(app, text)
assert_node(
doctree,
[nodes.document, (nodes.target, [nodes.math_block, 'E = mc^2\n\n'])])
assert_node(doctree[1],
nodes.math_block,
docname='index',
label="eq2",
number=2)
# :label: option without value
text = ('.. math:: E = mc^2\n' ' :label:\n')
doctree = restructuredtext.parse(app, text)
assert_node(
doctree,
[nodes.document, (nodes.target, [nodes.math_block, 'E = mc^2\n\n'])])
assert_node(doctree[1],
nodes.math_block,
ids=['equation-index-0'],
docname='index',
label="index:0",
number=3)
def test_rst_prolog(app, status, warning):
app.builder.build_all()
rst = pickle.loads((app.doctreedir / 'restructuredtext.doctree').bytes())
md = pickle.loads((app.doctreedir / 'markdown.doctree').bytes())
# rst_prolog
assert_node(rst[0], nodes.paragraph)
assert_node(rst[0][0], nodes.emphasis)
assert_node(rst[0][0][0], nodes.Text)
assert rst[0][0][0] == 'Hello world'
# rst_epilog
assert_node(rst[-1], nodes.section)
assert_node(rst[-1][-1], nodes.paragraph)
assert_node(rst[-1][-1][0], nodes.emphasis)
assert_node(rst[-1][-1][0][0], nodes.Text)
assert rst[-1][-1][0][0] == 'Good-bye world'
# rst_prolog & rst_epilog on exlucding reST parser
assert not md.rawsource.startswith('*Hello world*.')
assert not md.rawsource.endswith('*Good-bye world*.\n')
def test_samp():
emph_literal_role = EmphasizedLiteral()
# normal case
text = 'print 1+{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0],
[nodes.literal, ("print 1+", [nodes.emphasis, "variable"])])
assert msg == []
# two emphasis items
text = 'print {1}+{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0], [
nodes.literal,
("print ", [nodes.emphasis, "1"], "+", [nodes.emphasis, "variable"])
])
assert msg == []
# empty curly brace
text = 'print 1+{}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0], [nodes.literal, "print 1+{}"])
assert msg == []
# half-opened variable
text = 'print 1+{variable'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0], [nodes.literal, "print 1+{variable"])
assert msg == []
# nested
text = 'print 1+{{variable}}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(
ret[0],
[nodes.literal, ("print 1+", [nodes.emphasis, "{variable"], "}")])
assert msg == []
# emphasized item only
text = '{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0], [nodes.literal, nodes.emphasis, "variable"])
assert msg == []
# escaping
text = r'print 1+\{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0], [nodes.literal, "print 1+{variable}"])
assert msg == []
# escaping (2)
text = r'print 1+\{{variable}\}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(
ret[0],
[nodes.literal, ("print 1+{", [nodes.emphasis, "variable"], "}")])
assert msg == []
# escape a backslash
text = r'print 1+\\{variable}'
ret, msg = emph_literal_role('samp', text, text, 0, Mock())
assert_node(ret[0],
[nodes.literal, ("print 1+\\", [nodes.emphasis, "variable"])])
assert msg == []
def test_code_directive(app):
# normal case
text = ('.. code::\n' '\n' ' print("hello world")\n')
doctree = restructuredtext.parse(app, text)
assert_node(doctree,
[nodes.document, nodes.literal_block, 'print("hello world")'])
assert_node(doctree[0], language="default", highlight_args={})
# with language
text = ('.. code:: python\n' '\n' ' print("hello world")\n')
doctree = restructuredtext.parse(app, text)
assert_node(doctree,
[nodes.document, nodes.literal_block, 'print("hello world")'])
assert_node(doctree[0], language="python", highlight_args={})
# :number-lines: option
text = ('.. code:: python\n'
' :number-lines:\n'
'\n'
' print("hello world")\n')
doctree = restructuredtext.parse(app, text)
assert_node(doctree,
[nodes.document, nodes.literal_block, 'print("hello world")'])
assert_node(doctree[0], language="python", linenos=True, highlight_args={})
# :number-lines: option
text = ('.. code:: python\n'
' :number-lines: 5\n'
'\n'
' print("hello world")\n')
doctree = restructuredtext.parse(app, text)
assert_node(doctree,
[nodes.document, nodes.literal_block, 'print("hello world")'])
assert_node(doctree[0],
language="python",
linenos=True,
highlight_args={'linenostart': 5})
def test_info_field_list(app):
text = (".. py:module:: example\n"
".. py:class:: Class\n"
"\n"
" :param str name: blah blah\n"
" :param age: blah blah\n"
" :type age: int\n")
doctree = restructuredtext.parse(app, text)
print(doctree)
assert_node(doctree, (nodes.target,
addnodes.index,
addnodes.index,
[desc, ([desc_signature, ([desc_annotation, "class "],
[desc_addname, "example."],
[desc_name, "Class"])],
[desc_content, nodes.field_list, nodes.field])]))
assert_node(doctree[3][1][0][0],
([nodes.field_name, "Parameters"],
[nodes.field_body, nodes.bullet_list, ([nodes.list_item, nodes.paragraph],
[nodes.list_item, nodes.paragraph])]))
# :param str name:
assert_node(doctree[3][1][0][0][1][0][0][0],
([addnodes.literal_strong, "name"],
" (",
[pending_xref, addnodes.literal_emphasis, "str"],
")",
" -- ",
"blah blah"))
assert_node(doctree[3][1][0][0][1][0][0][0][2], pending_xref,
refdomain="py", reftype="class", reftarget="str",
**{"py:module": "example", "py:class": "Class"})
# :param age: + :type age:
assert_node(doctree[3][1][0][0][1][0][1][0],
([addnodes.literal_strong, "age"],
" (",
[pending_xref, addnodes.literal_emphasis, "int"],
")",
" -- ",
"blah blah"))
assert_node(doctree[3][1][0][0][1][0][1][0][2], pending_xref,
refdomain="py", reftype="class", reftarget="int",
**{"py:module": "example", "py:class": "Class"})
