source: rtems-central/rtemsqual/applconfig.py @ 5df0bec

Last change on this file since 5df0bec was 5df0bec, checked in by Sebastian Huber <sebastian.huber@…>, on 03/17/20 at 13:28:07

applconfig: Rework

  • Property mode set to 100644
File size: 4.2 KB
Line 
1# SPDX-License-Identifier: BSD-2-Clause
2""" Functions for application configuration documentation generation. """
3
4# Copyright (C) 2019, 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
27from typing import Dict
28
29from rtemsqual.content import SphinxContent
30from rtemsqual.items import Item, ItemCache
31
32ItemMap = Dict[str, Item]
33
34
35def _gather_groups(item: Item, groups: ItemMap) -> None:
36    for child in item.children:
37        _gather_groups(child, groups)
38    if item["type"] == "interface" and item[
39            "interface-type"] == "appl-config-group":
40        groups[item.uid] = item
41
42
43def _gather_options(item: Item, options: ItemMap) -> None:
44    for child in item.children:
45        _gather_options(child, options)
46    if item["type"] == "interface" and item[
47            "interface-type"] == "appl-config-option":
48        options[item.uid] = item
49
50
51def _generate_content(group: Item, options: ItemMap) -> SphinxContent:
52    content = SphinxContent()
53    group.register_license_and_copyrights(content)
54    content.add_header(group["appl-config-group-name"], level="=")
55    content.add_blank_line()
56    content.add_lines(group["appl-config-group-description"])
57    for item in sorted(options.values(), key=lambda x: x.uid):
58        name = item["appl-config-option-name"]
59        item.register_license_and_copyrights(content)
60        content.add_index_entries([name] + item["appl-config-option-index"])
61        content.add_blank_line()
62        content.add_label(name)
63        content.add_blank_line()
64        content.add_header(name, level="-")
65        content.add_definition_item("CONSTANT:", f"``{name}``")
66        content.add_definition_item("DATA TYPE:",
67                                    item["appl-config-option-data-type"])
68        content.add_definition_item("RANGE:", item["appl-config-option-range"])
69        content.add_definition_item("DEFAULT VALUE:",
70                                    item["appl-config-option-default-value"])
71        content.add_definition_item("DESCRIPTION:",
72                                    item["appl-config-option-description"])
73        content.add_definition_item("NOTES:", item["appl-config-option-notes"])
74    content.add_licence_and_copyrights()
75    return content
76
77
78def generate(config: dict, item_cache: ItemCache) -> None:
79    """
80    Generates application configuration documentation sources according to the
81    configuration.
82
83    :param config: A dictionary with configuration entries.
84    :param item_cache: The specification item cache containing the application
85                       configuration groups and options.
86    """
87    groups = {}  # type: ItemMap
88    for item in item_cache.top_level.values():
89        _gather_groups(item, groups)
90
91    for group_config in config["groups"]:
92        group = groups[group_config["uid"]]
93        options = {}  # type: ItemMap
94        _gather_options(group, options)
95        content = _generate_content(group, options)
96        content.write(group_config["target"])
Note: See TracBrowser for help on using the repository browser.