diff options
| -rw-r--r-- | rtemsqual/applconfig.py | 94 | ||||
| -rw-r--r-- | rtemsqual/interfacedoc.py | 37 | ||||
| -rw-r--r-- | rtemsqual/sphinxcontent.py | 12 | ||||
| -rw-r--r-- | rtemsqual/tests/spec-applconfig/a.yml | 13 | ||||
| -rw-r--r-- | rtemsqual/tests/spec-applconfig/func.yml | 21 | ||||
| -rw-r--r-- | rtemsqual/tests/spec-applconfig/td.yml | 14 | ||||
| -rw-r--r-- | rtemsqual/tests/spec/interface-appl-config-more.yml | 33 | ||||
| -rw-r--r-- | rtemsqual/tests/spec/interface-appl-config-option.yml | 21 | ||||
| -rw-r--r-- | rtemsqual/tests/spec/interface-more.yml | 4 | ||||
| -rw-r--r-- | rtemsqual/tests/test_applconfig.py | 10 |
10 files changed, 225 insertions, 34 deletions
diff --git a/rtemsqual/applconfig.py b/rtemsqual/applconfig.py index 05985abb..30de9661 100644 --- a/rtemsqual/applconfig.py +++ b/rtemsqual/applconfig.py @@ -26,8 +26,9 @@ from typing import Any, Dict, List, Optional -from rtemsqual.sphinxcontent import SphinxContent -from rtemsqual.items import Item, ItemCache +from rtemsqual.sphinxcontent import SphinxContent, SphinxMapper +from rtemsqual.items import EmptyItem, Item, ItemCache, ItemGetValueContext, \ + ItemMapper ItemMap = Dict[str, Item] @@ -56,9 +57,14 @@ class _ContentAdaptor: By default, Sphinx content is generated. """ - def __init__(self, content: Any) -> None: + def __init__(self, mapper: ItemMapper, content: Any) -> None: + self.mapper = mapper self.content = content + def substitute(self, text: Optional[str]) -> str: + """ Substitutes the optional text using the item mapper. """ + return self.mapper.substitute(text) + def add_group(self, name: str, description: str) -> None: """ Adds an option group. """ self.content.add_header(name, level=2) @@ -111,14 +117,14 @@ class _ContentAdaptor: class _SphinxContentAdaptor(_ContentAdaptor): - def __init__(self) -> None: - super().__init__(SphinxContent()) + def __init__(self, mapper: ItemMapper) -> None: + super().__init__(mapper, SphinxContent()) def _generate_feature(content: _ContentAdaptor, item: Item, option_type: str) -> None: content.add_option_default_config( - _OPTION_DEFAULT_CONFIG[option_type](item)) + content.substitute(_OPTION_DEFAULT_CONFIG[option_type](item))) def _generate_min_max(lines: List[str], value: str, word: str) -> None: @@ -209,7 +215,8 @@ def _generate_constraint(content: _ContentAdaptor, item: Item) -> None: _generate_item_max(lines, constraints) _generate_item_set(lines, constraints) _generate_item_texts(lines, constraints) - content.add_option_value_constraints(lines) + content.add_option_value_constraints( + [content.substitute(line) for line in lines]) def _generate_initializer_or_integer(content: _ContentAdaptor, item: Item, @@ -217,7 +224,7 @@ def _generate_initializer_or_integer(content: _ContentAdaptor, item: Item, default_value = item["default-value"] if not isinstance(default_value, str) or " " not in default_value: default_value = f"The default value is {default_value}." - content.add_option_default_value(default_value) + content.add_option_default_value(content.substitute(default_value)) _generate_constraint(content, item) @@ -231,19 +238,80 @@ _OPTION_GENERATORS = { def _generate(group: Item, options: ItemMap, content: _ContentAdaptor) -> None: content.register_license_and_copyrights_of_item(group) - content.add_group(group["name"], group["description"]) + content.add_group(group["name"], content.substitute(group["description"])) for item in sorted(options.values(), key=lambda x: x["name"]): + content.mapper.item = item name = item["name"] content.register_license_and_copyrights_of_item(item) content.add_option(name, item["index-entries"]) option_type = item["appl-config-option-type"] content.add_option_type(_OPTION_TYPES[option_type]) _OPTION_GENERATORS[option_type](content, item, option_type) - content.add_option_description(item["description"]) - content.add_option_notes(item["notes"]) + content.add_option_description(content.substitute(item["description"])) + content.add_option_notes(content.substitute(item["notes"])) content.add_licence_and_copyrights() +def _get_value_none(_ctx: ItemGetValueContext) -> Any: + return None + + +def _sphinx_ref(ref: str) -> str: + return f":ref:`{ref}`" + + +_PTHREAD_NAME_NP = "http://man7.org/linux/man-pages/man3/" \ + "pthread_setname_np.3.html" + +_SPHINX_DOC_REFS = { + "config-scheduler-clustered": + _sphinx_ref("ConfigurationSchedulersClustered"), + "config-scheduler-table": _sphinx_ref("ConfigurationSchedulerTable"), + "config-unlimited-objects": _sphinx_ref("ConfigUnlimitedObjects"), + "mp-proxies": _sphinx_ref("MPCIProxies"), + "mrsp": _sphinx_ref("MrsP"), + "pthread-setname-np": f"`PTHREAD_SETNAME_NP(3) <{_PTHREAD_NAME_NP}>`_", + "scheduler-cbs": _sphinx_ref("SchedulerCBS"), + "scheduler-concepts": _sphinx_ref("SchedulingConcepts"), + "scheduler-edf": _sphinx_ref("SchedulerEDF"), + "scheduler-priority": _sphinx_ref("SchedulerPriority"), + "scheduler-priority-simple": _sphinx_ref("SchedulerPrioritySimple"), + "scheduler-smp-edf": _sphinx_ref("SchedulerSMPEDF"), + "scheduler-smp-priority-affinity": + _sphinx_ref("SchedulerSMPPriorityAffinity"), + "scheduler-smp-priority": _sphinx_ref("SchedulerSMPPriority"), + "scheduler-smp-priority-simple": _sphinx_ref("SchedulerSMPPrioritySimple"), + "terminate": _sphinx_ref("Terminate"), +} + + +def _get_value_sphinx_reference(ctx: ItemGetValueContext) -> Any: + return _SPHINX_DOC_REFS[ctx.key] + + +def _get_value_sphinx_function(ctx: ItemGetValueContext) -> Any: + return f"``{ctx.value[ctx.key]}()``" + + +def _get_value_sphinx_code(ctx: ItemGetValueContext) -> Any: + return f"``{ctx.value[ctx.key]}``" + + +def _add_sphinx_get_values(mapper: ItemMapper) -> None: + for key in _SPHINX_DOC_REFS: + for opt in ["feature-enable", "feature", "initializer", "integer"]: + doc_ref = f"interface/appl-config-option/{opt}:/document-reference" + mapper.add_get_value(doc_ref, _get_value_none) + mapper.add_get_value(f"{doc_ref}/{key}", + _get_value_sphinx_reference) + mapper.add_get_value("interface/function:/name", + _get_value_sphinx_function) + mapper.add_get_value("interface/macro:/name", _get_value_sphinx_function) + mapper.add_get_value("interface/struct:/name", _get_value_sphinx_code) + mapper.add_get_value("interface/typedef:/name", _get_value_sphinx_code) + mapper.add_get_value("interface/union:/name", _get_value_sphinx_code) + + def generate(config: dict, item_cache: ItemCache) -> None: """ Generates application configuration documentation sources according to the @@ -253,6 +321,8 @@ def generate(config: dict, item_cache: ItemCache) -> None: :param item_cache: The specification item cache containing the application configuration groups and options. """ + sphinx_mapper = SphinxMapper(EmptyItem()) + _add_sphinx_get_values(sphinx_mapper) for group_config in config["groups"]: group = item_cache[group_config["uid"]] assert group.type == "interface/appl-config-group" @@ -260,6 +330,6 @@ def generate(config: dict, item_cache: ItemCache) -> None: for child in group.children("appl-config-group-member"): assert child.type.startswith("interface/appl-config-option") options[child.uid] = child - sphinx_content = _SphinxContentAdaptor() + sphinx_content = _SphinxContentAdaptor(sphinx_mapper) _generate(group, options, sphinx_content) sphinx_content.write(group_config["target"]) diff --git a/rtemsqual/interfacedoc.py b/rtemsqual/interfacedoc.py index ffa681b4..8402e922 100644 --- a/rtemsqual/interfacedoc.py +++ b/rtemsqual/interfacedoc.py @@ -30,7 +30,8 @@ import os from typing import Any, Callable, Dict, List from rtemsqual.content import CContent, enabled_by_to_exp, ExpressionMapper -from rtemsqual.sphinxcontent import get_label, get_reference, SphinxContent +from rtemsqual.sphinxcontent import get_label, get_reference, SphinxContent, \ + SphinxMapper from rtemsqual.items import Item, ItemCache, ItemGetValueContext, ItemMapper ItemMap = Dict[str, Item] @@ -48,23 +49,25 @@ def _get_reference(name: str) -> str: return get_reference(get_label(f"{INTERFACE}{name}"), f"{name}()") +def _get_value_forward_declaration(ctx: ItemGetValueContext) -> Any: + return _forward_declaration(ctx.item) + + class _CodeMapper(ItemMapper): - def get_value(self, ctx: ItemGetValueContext) -> Any: - if ctx.type_path_key == "interface/forward-declaration:/name": - return _forward_declaration(ctx.item) - raise KeyError - - -class _Mapper(_CodeMapper): - def get_value(self, ctx: ItemGetValueContext) -> Any: - try: - return super().get_value(ctx) - except KeyError: - if ctx.type_path_key == "interface/function:/name": - return _get_reference(ctx.value[ctx.key]) - if ctx.type_path_key == "interface/appl-config-option:/name": - return f":ref:`{ctx.value[ctx.key]}`" - raise KeyError + def __init__(self, item: Item): + super().__init__(item) + self.add_get_value("interface/forward-declaration:/name", + _get_value_forward_declaration) + + +def _get_value_function(ctx: ItemGetValueContext) -> Any: + return _get_reference(ctx.value[ctx.key]) + + +class _Mapper(SphinxMapper): + def __init__(self, item: Item): + super().__init__(item) + self.add_get_value("interface/function:/name", _get_value_function) def _generate_introduction(target: str, group: Item, diff --git a/rtemsqual/sphinxcontent.py b/rtemsqual/sphinxcontent.py index 97639c78..c0abdd55 100644 --- a/rtemsqual/sphinxcontent.py +++ b/rtemsqual/sphinxcontent.py @@ -220,9 +220,21 @@ def _get_ref_term_plural(ctx: ItemGetValueContext) -> Any: return f":term:`{ctx.value['term']}s <{ctx.value['term']}>`" +def _get_appl_config_option(ctx: ItemGetValueContext) -> Any: + return f":ref:`{ctx.value[ctx.key]}`" + + class SphinxMapper(ItemMapper): """ Sphinx item mapper. """ def __init__(self, item: Item): super().__init__(item) self.add_get_value("glossary/term:/term", _get_ref_term) self.add_get_value("glossary/term:/plural", _get_ref_term_plural) + self.add_get_value("interface/appl-config-option/feature-enable:/name", + _get_appl_config_option) + self.add_get_value("interface/appl-config-option/feature:/name", + _get_appl_config_option) + self.add_get_value("interface/appl-config-option/initializer:/name", + _get_appl_config_option) + self.add_get_value("interface/appl-config-option/integer:/name", + _get_appl_config_option) diff --git a/rtemsqual/tests/spec-applconfig/a.yml b/rtemsqual/tests/spec-applconfig/a.yml index cc087da7..0e692aae 100644 --- a/rtemsqual/tests/spec-applconfig/a.yml +++ b/rtemsqual/tests/spec-applconfig/a.yml @@ -4,7 +4,18 @@ description: description a index-entries: - index a name: a -notes: notes a +notes: | + notes a + + references: + + * ${b:/name} + + * ${.:/document-reference/terminate} + + * ${func:/name} + + * ${td:/name} appl-config-option-type: feature copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) diff --git a/rtemsqual/tests/spec-applconfig/func.yml b/rtemsqual/tests/spec-applconfig/func.yml new file mode 100644 index 00000000..fc08ddc0 --- /dev/null +++ b/rtemsqual/tests/spec-applconfig/func.yml @@ -0,0 +1,21 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +brief: null +definition: + default: + body: null + params: [] + return: void + variants: [] +description: null +name: func +notes: null +params: [] +interface-type: function +links: [] +return: + return: null + return-values: [] +type: interface diff --git a/rtemsqual/tests/spec-applconfig/td.yml b/rtemsqual/tests/spec-applconfig/td.yml new file mode 100644 index 00000000..9ef5c4fa --- /dev/null +++ b/rtemsqual/tests/spec-applconfig/td.yml @@ -0,0 +1,14 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +brief: null +definition: + default: void ${.:/name} + variants: [] +description: null +name: td +notes: null +interface-type: typedef +links: [] +type: interface diff --git a/rtemsqual/tests/spec/interface-appl-config-more.yml b/rtemsqual/tests/spec/interface-appl-config-more.yml new file mode 100644 index 00000000..8a8ecc56 --- /dev/null +++ b/rtemsqual/tests/spec/interface-appl-config-more.yml @@ -0,0 +1,33 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: +- role: spec-member + uid: root +- role: spec-refinement + spec-key: appl-config-option-type + spec-value: feature + uid: interface-appl-config-option +- role: spec-refinement + spec-key: appl-config-option-type + spec-value: feature-enable + uid: interface-appl-config-option +- role: spec-refinement + spec-key: appl-config-option-type + spec-value: integer + uid: interface-appl-config-option +- role: spec-refinement + spec-key: appl-config-option-type + spec-value: initializer + uid: interface-appl-config-option +spec-description: null +spec-example: null +spec-info: + dict: + attributes: {} + description: null + mandatory-attributes: all +spec-name: Interface Application Configuration More +spec-type: interface-appl-config-more +type: spec diff --git a/rtemsqual/tests/spec/interface-appl-config-option.yml b/rtemsqual/tests/spec/interface-appl-config-option.yml new file mode 100644 index 00000000..bb6997b7 --- /dev/null +++ b/rtemsqual/tests/spec/interface-appl-config-option.yml @@ -0,0 +1,21 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: +- role: spec-member + uid: root +- role: spec-refinement + spec-key: interface-type + spec-value: appl-config-option + uid: interface +spec-description: null +spec-example: null +spec-info: + dict: + attributes: {} + description: null + mandatory-attributes: all +spec-name: Interface Application Configuration Option +spec-type: interface-appl-config-option +type: spec diff --git a/rtemsqual/tests/spec/interface-more.yml b/rtemsqual/tests/spec/interface-more.yml index 070f62f7..deaf1e60 100644 --- a/rtemsqual/tests/spec/interface-more.yml +++ b/rtemsqual/tests/spec/interface-more.yml @@ -11,10 +11,6 @@ links: uid: interface - role: spec-refinement spec-key: interface-type - spec-value: appl-config-option - uid: interface -- role: spec-refinement - spec-key: interface-type spec-value: struct uid: interface - role: spec-refinement diff --git a/rtemsqual/tests/test_applconfig.py b/rtemsqual/tests/test_applconfig.py index 8c210ca4..cfb532e0 100644 --- a/rtemsqual/tests/test_applconfig.py +++ b/rtemsqual/tests/test_applconfig.py @@ -74,6 +74,16 @@ DESCRIPTION: NOTES: notes a + references: + + * :ref:`b` + + * :ref:`Terminate` + + * ``func()`` + + * ``td`` + .. index:: b .. _b: |