1""" 2 test_rst_domain 3 ~~~~~~~~~~~~~~~ 4 5 Tests the reStructuredText domain. 6 7 :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. 8 :license: BSD, see LICENSE for details. 9""" 10 11from sphinx import addnodes 12from sphinx.addnodes import (desc, desc_addname, desc_annotation, desc_content, desc_name, 13 desc_signature) 14from sphinx.domains.rst import parse_directive 15from sphinx.testing import restructuredtext 16from sphinx.testing.util import assert_node 17 18 19def test_parse_directive(): 20 s = parse_directive(' foö ') 21 assert s == ('foö', '') 22 23 s = parse_directive(' .. foö :: ') 24 assert s == ('foö', '') 25 26 s = parse_directive('.. foö:: args1 args2') 27 assert s == ('foö', ' args1 args2') 28 29 s = parse_directive('.. :: bar') 30 assert s == ('.. :: bar', '') 31 32 33def test_rst_directive(app): 34 # bare 35 text = ".. rst:directive:: toctree" 36 doctree = restructuredtext.parse(app, text) 37 assert_node(doctree, (addnodes.index, 38 [desc, ([desc_signature, desc_name, ".. toctree::"], 39 [desc_content, ()])])) 40 assert_node(doctree[0], 41 entries=[("single", "toctree (directive)", "directive-toctree", "", None)]) 42 assert_node(doctree[1], addnodes.desc, desctype="directive", 43 domain="rst", objtype="directive", noindex=False) 44 45 # decorated 46 text = ".. rst:directive:: .. toctree::" 47 doctree = restructuredtext.parse(app, text) 48 assert_node(doctree, (addnodes.index, 49 [desc, ([desc_signature, desc_name, ".. toctree::"], 50 [desc_content, ()])])) 51 assert_node(doctree[0], 52 entries=[("single", "toctree (directive)", "directive-toctree", "", None)]) 53 assert_node(doctree[1], addnodes.desc, desctype="directive", 54 domain="rst", objtype="directive", noindex=False) 55 56 57def test_rst_directive_with_argument(app): 58 text = ".. rst:directive:: .. toctree:: foo bar baz" 59 doctree = restructuredtext.parse(app, text) 60 assert_node(doctree, (addnodes.index, 61 [desc, ([desc_signature, ([desc_name, ".. toctree::"], 62 [desc_addname, " foo bar baz"])], 63 [desc_content, ()])])) 64 assert_node(doctree[0], 65 entries=[("single", "toctree (directive)", "directive-toctree", "", None)]) 66 assert_node(doctree[1], addnodes.desc, desctype="directive", 67 domain="rst", objtype="directive", noindex=False) 68 69 70def test_rst_directive_option(app): 71 text = ".. rst:directive:option:: foo" 72 doctree = restructuredtext.parse(app, text) 73 assert_node(doctree, (addnodes.index, 74 [desc, ([desc_signature, desc_name, ":foo:"], 75 [desc_content, ()])])) 76 assert_node(doctree[0], 77 entries=[("single", ":foo: (directive option)", 78 "directive-option-foo", "", "F")]) 79 assert_node(doctree[1], addnodes.desc, desctype="directive:option", 80 domain="rst", objtype="directive:option", noindex=False) 81 82 83def test_rst_directive_option_with_argument(app): 84 text = ".. rst:directive:option:: foo: bar baz" 85 doctree = restructuredtext.parse(app, text) 86 assert_node(doctree, (addnodes.index, 87 [desc, ([desc_signature, ([desc_name, ":foo:"], 88 [desc_annotation, " bar baz"])], 89 [desc_content, ()])])) 90 assert_node(doctree[0], 91 entries=[("single", ":foo: (directive option)", 92 "directive-option-foo", "", "F")]) 93 assert_node(doctree[1], addnodes.desc, desctype="directive:option", 94 domain="rst", objtype="directive:option", noindex=False) 95 96 97def test_rst_directive_option_type(app): 98 text = (".. rst:directive:option:: foo\n" 99 " :type: directives.flags\n") 100 doctree = restructuredtext.parse(app, text) 101 assert_node(doctree, (addnodes.index, 102 [desc, ([desc_signature, ([desc_name, ":foo:"], 103 [desc_annotation, " (directives.flags)"])], 104 [desc_content, ()])])) 105 assert_node(doctree[0], 106 entries=[("single", ":foo: (directive option)", 107 "directive-option-foo", "", "F")]) 108 assert_node(doctree[1], addnodes.desc, desctype="directive:option", 109 domain="rst", objtype="directive:option", noindex=False) 110 111 112def test_rst_directive_and_directive_option(app): 113 text = (".. rst:directive:: foo\n" 114 "\n" 115 " .. rst:directive:option:: bar\n") 116 doctree = restructuredtext.parse(app, text) 117 assert_node(doctree, (addnodes.index, 118 [desc, ([desc_signature, desc_name, ".. foo::"], 119 [desc_content, (addnodes.index, 120 desc)])])) 121 assert_node(doctree[1][1][0], 122 entries=[("pair", "foo (directive); :bar: (directive option)", 123 "directive-option-foo-bar", "", "B")]) 124 assert_node(doctree[1][1][1], ([desc_signature, desc_name, ":bar:"], 125 [desc_content, ()])) 126 assert_node(doctree[1][1][1], addnodes.desc, desctype="directive:option", 127 domain="rst", objtype="directive:option", noindex=False) 128 129 130def test_rst_role(app): 131 text = ".. rst:role:: ref" 132 doctree = restructuredtext.parse(app, text) 133 assert_node(doctree, (addnodes.index, 134 [desc, ([desc_signature, desc_name, ":ref:"], 135 [desc_content, ()])])) 136 assert_node(doctree[0], 137 entries=[("single", "ref (role)", "role-ref", "", None)]) 138 assert_node(doctree[1], addnodes.desc, desctype="role", 139 domain="rst", objtype="role", noindex=False) 140