# SPDX-License-Identifier: BSD-2-Clause
""" Unit tests for the rtemsspec.specdoc module. """
# Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
import os
from rtemsspec.items import ItemCache
from rtemsspec.specdoc import document
from rtemsspec.tests.util import create_item_cache_config_and_copy_spec
def test_document(tmpdir):
item_cache_config = create_item_cache_config_and_copy_spec(
tmpdir, "spec-doc")
item_cache_config["spec-type-root-uid"] = "/root"
item_cache = ItemCache(item_cache_config)
assert item_cache["/root"].type == "spec"
doc_target = os.path.join(tmpdir, "items.rst")
config = {
"root-type": "/root",
"doc-target": doc_target,
}
document(config, item_cache)
with open(doc_target, "r") as src:
content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
.. This file was automatically generated. Do not edit it manually.
.. Please have a look at
..
.. https://docs.rtems.org/branches/master/eng/req/howto.html
..
.. for information how to maintain and re-generate this file.
.. _ReqEngSpecificationItems:
Specification Items
===================
.. _ReqEngSpecificationItemHierarchy:
Specification Item Hierarchy
----------------------------
The specification item types have the following hierarchy:
* :ref:`SpecTypeRoot`
* :ref:`SpecTypeA`
* :ref:`SpecTypeB`
.. _ReqEngSpecificationItemTypes:
Specification Item Types
------------------------
.. _SpecTypeRoot:
Root
^^^^
A value of this type shall be of one of the following variants:
* The value may be a boolean. A reference to :ref:`SpecTypeRoot`. The value
shall be true.
* The value may be a set of attributes. All explicit attributes shall be
specified. The explicit attributes for this type are:
type
The attribute value shall be a :ref:`SpecTypeName`.
In addition to the explicit attributes, generic attributes may be specified.
Each generic attribute key shall be a :ref:`SpecTypeName`. Each generic
attribute value shall be a :ref:`SpecTypeRoot`.
* The value may be a floating-point number. The value shall be equal to 0.0.
* The value may be an integer number. The value shall be equal to 0.
* The value may be a list. Each list element shall be a :ref:`SpecTypeRoot`.
* There may by be no value (null).
* The value may be a string. The value
* shall meet,
* shall contain an element of
* "``a``",
* "``b``", and
* "``c``",
* and, shall be equal to "``d``",
* and, shall be greater than or equal to "``e``",
* and, shall be greater than "``f``",
* and, shall be an element of
* "``g``", and
* "``h``",
* and, shall be less than or equal to "``i``",
* and, shall be less than "``j``",
* and, shall be not equal to "``k``",
* and, shall match with the regular expression "``l``",
* and, shall be true,
* and, shall be a valid item UID,
* or,
* shall be an element of,
* or, shall be an element of
* "``x``",
* or, shall not meet,
* shall not contain an element of
* "``a``",
* "``b``", and
* "``c``",
* or, shall be not equal to "``d``",
* or, shall be less than "``e``",
* or, shall be less than or equal to "``f``",
* or, shall not be an element of
* "``g``", and
* "``h``",
* or, shall be greater than "``i``",
* or, shall be greater than or equal to "``j``",
* or, shall be equal to "``k``",
* or, shall not match with the regular expression "``l``",
* or, shall be false,
* or, shall be an invalid item UID.
This type is refined by the following types:
* :ref:`SpecTypeA`
* :ref:`SpecTypeB`
This type is used by the following types:
* :ref:`SpecTypeRoot`
.. _SpecTypeA:
A
^
This type refines the :ref:`SpecTypeRoot` though the ``type`` attribute if the
value is ``spec``.
The explicit attributes for this type are:
a
The attribute value shall be an :ref:`SpecTypeA`.
This type is used by the following types:
* :ref:`SpecTypeA`
Please have a look at the following example:
.. code-block:: yaml
a: null
.. _SpecTypeB:
B
^
This type refines the following types:
* :ref:`SpecTypeD` though the ``d1`` attribute if the value is ``b``
* :ref:`SpecTypeRoot` though the ``type`` attribute if the value is ``b``
Generic attributes may be specified. Each generic attribute key shall be a
:ref:`SpecTypeName`. Each generic attribute value shall be a list. Each list
element shall be a string.
.. _ReqEngSpecificationAttributeSetsAndValueTypes:
Specification Attribute Sets and Value Types
--------------------------------------------
.. _SpecTypeC:
C
^
Only the ``c`` attribute is mandatory. The explicit attributes for this type
are:
c
The attribute value shall be a floating-point number.
.. _SpecTypeD:
D
^
The following explicit attributes are mandatory:
* ``d1``
* ``d2``
The explicit attributes for this type are:
d1
The attribute value shall be a :ref:`SpecTypeName`.
d2
The attribute shall have no value.
This type is refined by the following types:
* :ref:`SpecTypeB`
.. _SpecTypeName:
Name
^^^^
The value shall be a string. A string is a valid name if it matches with the
``^([a-z][a-z0-9-]*|SPDX-License-Identifier)$`` regular expression.
This type is used by the following types:
* :ref:`SpecTypeB`
* :ref:`SpecTypeD`
* :ref:`SpecTypeRoot`
.. _SpecTypeUID:
UID
^^^
The value shall be a string. The string shall be a valid absolute or relative
item UID.
"""
assert content == src.read()