1"""
2    test_util_docstrings
3    ~~~~~~~~~~~~~~~~~~~~
4
5    Test sphinx.util.docstrings.
6
7    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
8    :license: BSD, see LICENSE for details.
9"""
10
11from sphinx.util.docstrings import extract_metadata, prepare_commentdoc, prepare_docstring
12
13
14def test_extract_metadata():
15    metadata = extract_metadata(":meta foo: bar\n"
16                                ":meta baz:\n")
17    assert metadata == {'foo': 'bar', 'baz': ''}
18
19    # field_list like text following just after paragaph is not a field_list
20    metadata = extract_metadata("blah blah blah\n"
21                                ":meta foo: bar\n"
22                                ":meta baz:\n")
23    assert metadata == {}
24
25    # field_list like text following after blank line is a field_list
26    metadata = extract_metadata("blah blah blah\n"
27                                "\n"
28                                ":meta foo: bar\n"
29                                ":meta baz:\n")
30    assert metadata == {'foo': 'bar', 'baz': ''}
31
32    # non field_list item breaks field_list
33    metadata = extract_metadata(":meta foo: bar\n"
34                                "blah blah blah\n"
35                                ":meta baz:\n")
36    assert metadata == {'foo': 'bar'}
37
38
39def test_prepare_docstring():
40    docstring = """multiline docstring
41
42                Lorem ipsum dolor sit amet, consectetur adipiscing elit,
43                sed do eiusmod tempor incididunt ut labore et dolore magna
44                aliqua::
45
46                  Ut enim ad minim veniam, quis nostrud exercitation
47                    ullamco laboris nisi ut aliquip ex ea commodo consequat.
48                """
49
50    assert (prepare_docstring(docstring) ==
51            ["multiline docstring",
52             "",
53             "Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
54             "sed do eiusmod tempor incididunt ut labore et dolore magna",
55             "aliqua::",
56             "",
57             "  Ut enim ad minim veniam, quis nostrud exercitation",
58             "    ullamco laboris nisi ut aliquip ex ea commodo consequat.",
59             ""])
60
61    docstring = """
62
63                multiline docstring with leading empty lines
64                """
65    assert (prepare_docstring(docstring) ==
66            ["multiline docstring with leading empty lines",
67             ""])
68
69    docstring = "single line docstring"
70    assert (prepare_docstring(docstring) ==
71            ["single line docstring",
72             ""])
73
74
75def test_prepare_commentdoc():
76    assert prepare_commentdoc("hello world") == []
77    assert prepare_commentdoc("#: hello world") == ["hello world", ""]
78    assert prepare_commentdoc("#:  hello world") == [" hello world", ""]
79    assert prepare_commentdoc("#: hello\n#: world\n") == ["hello", "world", ""]
80