source: rtems-central/rtemsspec/tests/test_interfacedoc.py @ d9fa7d6

Last change on this file since d9fa7d6 was d9fa7d6, checked in by Sebastian Huber <sebastian.huber@…>, on Jul 24, 2020 at 6:33:04 AM

interfacedoc: Simplify interface references

  • Property mode set to 100644
File size: 6.1 KB
Line 
1# SPDX-License-Identifier: BSD-2-Clause
2""" Unit tests for the rtemsspec.interfacedoc module. """
3
4# Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
5#
6# Redistribution and use in source and binary forms, with or without
7# modification, are permitted provided that the following conditions
8# are met:
9# 1. Redistributions of source code must retain the above copyright
10#    notice, this list of conditions and the following disclaimer.
11# 2. Redistributions in binary form must reproduce the above copyright
12#    notice, this list of conditions and the following disclaimer in the
13#    documentation and/or other materials provided with the distribution.
14#
15# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
19# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25# POSSIBILITY OF SUCH DAMAGE.
26
27import os
28import pytest
29
30from rtemsspec.interfacedoc import generate
31from rtemsspec.items import EmptyItemCache, ItemCache
32from rtemsspec.tests.util import create_item_cache_config_and_copy_spec
33
34
35def test_interfacedoc(tmpdir):
36    doc_config = {}
37    doc_config["group"] = "/gb"
38    introduction_rst = os.path.join(tmpdir, "introduction.rst")
39    doc_config["introduction-target"] = introduction_rst
40    directives_rst = os.path.join(tmpdir, "directives.rst")
41    doc_config["directives-target"] = directives_rst
42
43    doc_config_2 = {}
44    doc_config_2["group"] = "/ga"
45    introduction_2_rst = os.path.join(tmpdir, "introduction-2.rst")
46    doc_config_2["introduction-target"] = introduction_2_rst
47    directives_2_rst = os.path.join(tmpdir, "directives-2.rst")
48    doc_config_2["directives-target"] = directives_2_rst
49
50    item_cache_config = create_item_cache_config_and_copy_spec(
51        tmpdir, "spec-interface", with_spec_types=True)
52    generate([doc_config, doc_config_2], ItemCache(item_cache_config))
53
54    with open(introduction_rst, "r") as src:
55        content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
56
57.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
58
59.. _GroupBIntroduction:
60
61Introduction
62============
63
64The directives provided by the Group B are:
65
66* :ref:`InterfaceVeryLongFunction` - Very long function brief description.
67
68* :ref:`InterfaceVeryLongTypeFunction` - Function brief description with very
69  long return type.
70
71* :ref:`InterfaceVoidFunction`
72"""
73        assert content == src.read()
74
75    with open(directives_rst, "r") as src:
76        content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
77
78.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
79
80.. _GroupBDirectives:
81
82Directives
83==========
84
85.. _InterfaceVeryLongFunction:
86
87VeryLongFunction()
88------------------
89
90Very long function brief description.
91
92CALLING SEQUENCE:
93    .. code-block:: c
94
95        int VeryLongFunction(
96          int                  VeryLongParam0,
97          const struct Struct *VeryLongParam1,
98          struct Struct    *( *VeryLongParam2 )( void ),
99          struct Struct       *VeryLongParam3
100        );
101
102DIRECTIVE PARAMETERS:
103    VeryLongParam0
104        This parameter is very long parameter 0 with some super important and
105        extra very long description which makes a lot of sense.
106
107    VeryLongParam1
108        This parameter is very long parameter 1.
109
110    VeryLongParam2
111        This parameter is very long parameter 2.
112
113    VeryLongParam3
114        This parameter is very long parameter 3.
115
116DIRECTIVE RETURN VALUES:
117    1
118        is returned, in case A.
119
120    2
121        is returned, in case B.
122
123    Sometimes some value.  See :ref:`InterfaceFunction`.
124
125DESCRIPTION:
126    VeryLongFunction description.
127
128NOTES:
129    VeryLongFunction notes.
130
131.. _InterfaceVeryLongTypeFunction:
132
133VeryLongTypeFunction()
134----------------------
135
136Function brief description with very long return type.
137
138CALLING SEQUENCE:
139    .. code-block:: c
140
141        #if 1
142          NotSoVeryLongType VeryLongTypeFunction( void );
143        #else
144          VeryLongLongLongLongLongLongLongLongLongLongLongLongLongLongLongType
145          VeryLongTypeFunction( void );
146        #endif
147
148DIRECTIVE RETURN VALUES:
149    This function returns an object with a very long type.
150
151.. _InterfaceVoidFunction:
152
153VoidFunction()
154--------------
155
156CALLING SEQUENCE:
157    .. code-block:: c
158
159        #if 1
160          void VoidFunction( void );
161        #endif
162"""
163        assert content == src.read()
164
165    with open(introduction_2_rst, "r") as src:
166        content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
167
168.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
169
170.. _GroupAIntroduction:
171
172Introduction
173============
174
175Group A brief description.
176
177Group A description. The directives provided by the Group A are:
178
179* :ref:`InterfaceFunction` - Function brief description.
180"""
181        assert content == src.read()
182
183    with open(directives_2_rst, "r") as src:
184        content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
185
186.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
187
188.. _GroupADirectives:
189
190Directives
191==========
192
193.. _InterfaceFunction:
194
195Function()
196----------
197
198Function brief description.
199
200CALLING SEQUENCE:
201    .. code-block:: c
202
203        void Function( int Param0, const int *Param1, int *Param2, int *Param3 );
204
205DIRECTIVE PARAMETERS:
206    Param0
207        This parameter is parameter 0.
208
209    Param1
210        This parameter is parameter 1.
211
212    Param2
213        This parameter is parameter 2.
214
215    Param3
216        This parameter is parameter 3.
217
218DESCRIPTION:
219    Function description.  References to :ref:`InterfaceVeryLongFunction`,
220    Integer, Enum, DEFINE, VERY_LONG_MACRO, Variable, ENUMERATOR_0, Struct,
221    :ref:`a`, and interface.
222"""
223        assert content == src.read()
Note: See TracBrowser for help on using the repository browser.