summaryrefslogtreecommitdiffstats
path: root/tests/test_util/test_util_docstrings.py
blob: 813e84e975efa526bf355b6b8d1213edbfcde222 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
"""Test sphinx.util.docstrings."""

from sphinx.util.docstrings import prepare_commentdoc, prepare_docstring, separate_metadata


def test_separate_metadata():
    # metadata only
    text = (":meta foo: bar\n"
            ":meta baz:\n")
    docstring, metadata = separate_metadata(text)
    assert docstring == ''
    assert metadata == {'foo': 'bar', 'baz': ''}

    # non metadata field list item
    text = (":meta foo: bar\n"
            ":param baz:\n")
    docstring, metadata = separate_metadata(text)
    assert docstring == ':param baz:\n'
    assert metadata == {'foo': 'bar'}

    # field_list like text following just after paragraph is not a field_list
    text = ("blah blah blah\n"
            ":meta foo: bar\n"
            ":meta baz:\n")
    docstring, metadata = separate_metadata(text)
    assert docstring == text
    assert metadata == {}

    # field_list like text following after blank line is a field_list
    text = ("blah blah blah\n"
            "\n"
            ":meta foo: bar\n"
            ":meta baz:\n")
    docstring, metadata = separate_metadata(text)
    assert docstring == "blah blah blah\n\n"
    assert metadata == {'foo': 'bar', 'baz': ''}

    # non field_list item breaks field_list
    text = (":meta foo: bar\n"
            "blah blah blah\n"
            ":meta baz:\n")
    docstring, metadata = separate_metadata(text)
    assert docstring == ("blah blah blah\n"
                         ":meta baz:\n")
    assert metadata == {'foo': 'bar'}


def test_prepare_docstring():
    docstring = """multiline docstring

                Lorem ipsum dolor sit amet, consectetur adipiscing elit,
                sed do eiusmod tempor incididunt ut labore et dolore magna
                aliqua::

                  Ut enim ad minim veniam, quis nostrud exercitation
                    ullamco laboris nisi ut aliquip ex ea commodo consequat.
                """

    assert (prepare_docstring(docstring) ==
            ["multiline docstring",
             "",
             "Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
             "sed do eiusmod tempor incididunt ut labore et dolore magna",
             "aliqua::",
             "",
             "  Ut enim ad minim veniam, quis nostrud exercitation",
             "    ullamco laboris nisi ut aliquip ex ea commodo consequat.",
             ""])

    docstring = """

                multiline docstring with leading empty lines
                """
    assert (prepare_docstring(docstring) ==
            ["multiline docstring with leading empty lines",
             ""])

    docstring = "single line docstring"
    assert (prepare_docstring(docstring) ==
            ["single line docstring",
             ""])


def test_prepare_commentdoc():
    assert prepare_commentdoc("hello world") == []
    assert prepare_commentdoc("#: hello world") == ["hello world", ""]
    assert prepare_commentdoc("#:  hello world") == [" hello world", ""]
    assert prepare_commentdoc("#: hello\n#: world\n") == ["hello", "world", ""]