1"""
2    test_ext_autodoc_events
3    ~~~~~~~~~~~~~~~~~~~~~~~
4
5    Test the autodoc extension.  This tests mainly for autodoc events
6
7    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
8    :license: BSD, see LICENSE for details.
9"""
10
11import pytest
12
13from sphinx.ext.autodoc import between, cut_lines
14
15from .test_ext_autodoc import do_autodoc
16
17
18@pytest.mark.sphinx('html', testroot='ext-autodoc')
19def test_process_docstring(app):
20    def on_process_docstring(app, what, name, obj, options, lines):
21        lines.clear()
22        lines.append('my docstring')
23
24    app.connect('autodoc-process-docstring', on_process_docstring)
25
26    actual = do_autodoc(app, 'function', 'target.process_docstring.func')
27    assert list(actual) == [
28        '',
29        '.. py:function:: func()',
30        '   :module: target.process_docstring',
31        '',
32        '   my docstring',
33        '',
34    ]
35
36
37@pytest.mark.sphinx('html', testroot='ext-autodoc')
38def test_process_docstring_for_nondatadescriptor(app):
39    def on_process_docstring(app, what, name, obj, options, lines):
40        raise
41
42    app.connect('autodoc-process-docstring', on_process_docstring)
43
44    actual = do_autodoc(app, 'attribute', 'target.AttCls.a1')
45    assert list(actual) == [
46        '',
47        '.. py:attribute:: AttCls.a1',
48        '   :module: target',
49        '   :value: hello world',
50        '',
51    ]
52
53
54@pytest.mark.sphinx('html', testroot='ext-autodoc')
55def test_cut_lines(app):
56    app.connect('autodoc-process-docstring',
57                cut_lines(2, 2, ['function']))
58
59    actual = do_autodoc(app, 'function', 'target.process_docstring.func')
60    assert list(actual) == [
61        '',
62        '.. py:function:: func()',
63        '   :module: target.process_docstring',
64        '',
65        '   second line',
66        '',
67    ]
68
69
70@pytest.mark.sphinx('html', testroot='ext-autodoc')
71def test_between(app):
72    app.connect('autodoc-process-docstring',
73                between('---', ['function']))
74
75    actual = do_autodoc(app, 'function', 'target.process_docstring.func')
76    assert list(actual) == [
77        '',
78        '.. py:function:: func()',
79        '   :module: target.process_docstring',
80        '',
81        '   second line',
82        '',
83    ]
84
85
86@pytest.mark.sphinx('html', testroot='ext-autodoc')
87def test_between_exclude(app):
88    app.connect('autodoc-process-docstring',
89                between('---', ['function'], exclude=True))
90
91    actual = do_autodoc(app, 'function', 'target.process_docstring.func')
92    assert list(actual) == [
93        '',
94        '.. py:function:: func()',
95        '   :module: target.process_docstring',
96        '',
97        '   first line',
98        '   third line',
99        '',
100    ]
101
102
103@pytest.mark.sphinx('html', testroot='ext-autodoc')
104def test_skip_module_member(app):
105    def autodoc_skip_member(app, what, name, obj, skip, options):
106        if name == "Class":
107            return True  # Skip "Class" class in __all__
108        elif name == "raises":
109            return False  # Show "raises()" function (not in __all__)
110
111    app.connect('autodoc-skip-member', autodoc_skip_member)
112
113    options = {"members": None}
114    actual = do_autodoc(app, 'module', 'target', options)
115    assert list(actual) == [
116        '',
117        '.. py:module:: target',
118        '',
119        '',
120        '.. py:function:: raises(exc, func, *args, **kwds)',
121        '   :module: target',
122        '',
123        '   Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*.',
124        '',
125    ]
126