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