source: rtems-central/rtemsqual/glossary.py @ a5f3cc1

Last change on this file since a5f3cc1 was a5f3cc1, checked in by Sebastian Huber <sebastian.huber@…>, on May 6, 2020 at 8:31:57 AM

spec: Use item mapper for glossary terms

  • Property mode set to 100644
File size: 5.5 KB
Line 
1# SPDX-License-Identifier: BSD-2-Clause
2""" This module provides functions for glossary of terms 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
27import glob
28import re
29from typing import Any, Dict, Optional
30
31from rtemsqual.content import SphinxContent, SphinxMapper
32from rtemsqual.items import Item, ItemCache, ItemMapper
33
34ItemMap = Dict[str, Item]
35
36
37def _gather_glossary_groups(item: Item, glossary_groups: ItemMap) -> None:
38    for child in item.children():
39        _gather_glossary_groups(child, glossary_groups)
40    if item["type"] == "glossary" and item["glossary-type"] == "group":
41        glossary_groups[item.uid] = item
42
43
44def _gather_glossary_terms(item: Item, glossary_terms: ItemMap) -> None:
45    for child in item.children():
46        _gather_glossary_terms(child, glossary_terms)
47    if item["type"] == "glossary" and item["glossary-type"] == "term":
48        glossary_terms[item.uid] = item
49
50
51def _generate_glossary_content(terms: ItemMap) -> SphinxContent:
52    content = SphinxContent()
53    content.add_header("Glossary", level="*")
54    content.add(".. glossary::")
55    with content.indent():
56        content.append(":sorted:")
57    for item in sorted(terms.values(),
58                       key=lambda x: x["glossary-term"].lower()):
59        content.register_license_and_copyrights_of_item(item)
60        with content.indent():
61            text = SphinxMapper(item).substitute(item["text"])
62            content.add_definition_item(item["glossary-term"], text)
63    content.add_licence_and_copyrights()
64    return content
65
66
67def _make_glossary_term_uid(term: str) -> str:
68    return "/glos/term/" + re.sub(r"[^a-zA-Z0-9]+", "", term.replace(
69        "+", "X")).lower()
70
71
72def _find_glossary_terms(path: str, document_terms: ItemMap,
73                         project_terms: ItemMap) -> None:
74    for src in glob.glob(path + "/**/*.rst", recursive=True):
75        if src.endswith("glossary.rst"):
76            continue
77        with open(src, "r") as out:
78            for term in re.findall(":term:`([^`]+)`", out.read()):
79                uid = _make_glossary_term_uid(term)
80                document_terms[uid] = project_terms[uid]
81
82
83class _GlossaryMapper(ItemMapper):
84    def __init__(self, item: Item, document_terms: ItemMap):
85        super().__init__(item)
86        self._document_terms = document_terms
87
88    def get_value(self, item: Item, _path: str, _value: Any, key: str,
89                  _index: Optional[int]) -> Any:
90        """ Recursively adds glossary terms to the document terms. """
91        if key == "glossary-term":
92            if item.uid not in self._document_terms:
93                self._document_terms[item.uid] = item
94                _GlossaryMapper(item,
95                                self._document_terms).substitute(item["text"])
96        # The value of this substitute is unused.
97        return ""
98
99
100def _resolve_glossary_terms(document_terms: ItemMap) -> None:
101    for term in list(document_terms.values()):
102        _GlossaryMapper(term, document_terms).substitute(term["text"])
103
104
105def _generate_project_glossary(target: str, project_terms: ItemMap) -> None:
106    content = _generate_glossary_content(project_terms)
107    content.write(target)
108
109
110def _generate_document_glossary(config: dict, project_terms: ItemMap) -> None:
111    document_terms = {}  # type: ItemMap
112    for path in config["rest-source-paths"]:
113        _find_glossary_terms(path, document_terms, project_terms)
114    _resolve_glossary_terms(document_terms)
115    content = _generate_glossary_content(document_terms)
116    content.write(config["target"])
117
118
119def generate(config: dict, item_cache: ItemCache) -> None:
120    """
121    Generates glossaries of terms according to the configuration.
122
123    :param config: A dictionary with configuration entries.
124    :param item_cache: The specification item cache containing the glossary
125                       groups and terms.
126    """
127    groups = {}  # type: ItemMap
128    for item in item_cache.top_level.values():
129        _gather_glossary_groups(item, groups)
130
131    project_terms = {}  # type: ItemMap
132    for group in config["project-groups"]:
133        _gather_glossary_terms(groups[group], project_terms)
134
135    _generate_project_glossary(config["project-target"], project_terms)
136
137    for document_config in config["documents"]:
138        _generate_document_glossary(document_config, project_terms)
Note: See TracBrowser for help on using the repository browser.