From f313e5670bebb032cd438270321dbef2038ebc04 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 27 May 2020 16:18:19 +0200 Subject: specdoc: Use mapper substitutions for descriptions --- rtemsqual/specdoc.py | 32 ++++++++++++++++++++-------- rtemsqual/tests/spec-doc/root.yml | 3 ++- rtemsqual/tests/test_specdoc.py | 2 +- spec/spec/appl-config-option-constraints.yml | 4 ++-- spec/spec/appl-config-option.yml | 5 ++--- spec/spec/build-action-set-test-state.yml | 7 +++--- spec/spec/build-action.yml | 12 +++++------ spec/spec/build-ada-test-program.yml | 8 +++---- spec/spec/build-config-file.yml | 6 +++--- spec/spec/build-include.yml | 13 ++++++----- spec/spec/build-install-path.yml | 2 +- spec/spec/build-library.yml | 4 ++-- spec/spec/build-test-program.yml | 8 +++---- spec/spec/interface-container.yml | 6 +++--- spec/spec/interface-domain.yml | 6 +++--- spec/spec/interface-forward-declaration.yml | 6 +++--- spec/spec/interface-header-file.yml | 6 +++--- spec/spec/requirement-validation.yml | 7 +++--- 18 files changed, 75 insertions(+), 62 deletions(-) diff --git a/rtemsqual/specdoc.py b/rtemsqual/specdoc.py index 43ecc613..cd525234 100644 --- a/rtemsqual/specdoc.py +++ b/rtemsqual/specdoc.py @@ -27,7 +27,7 @@ from typing import Any, Dict, Iterator, Optional, Set, Tuple from rtemsqual.sphinxcontent import get_reference, get_section_label, \ - SphinxContent + SphinxContent, SphinxMapper from rtemsqual.items import Item, ItemCache from rtemsqual.specverify import NAME @@ -63,7 +63,12 @@ def _a_or_an(value: str) -> str: return "a" +def _get_ref_specification_type(value: Any, key: str) -> str: + return get_reference(get_section_label(value[key], _SECTION_PREFIX)) + + class _Documenter: + # pylint: disable=too-many-instance-attributes def __init__(self, item: Item, documenter_map: _DocumenterMap): self._name = item["spec-type"] self.section = item["spec-name"] @@ -72,9 +77,17 @@ class _Documenter: self._item = item self._documenter_map = documenter_map self.used_by = set() # type: Set[str] + self._mapper = SphinxMapper(item) + self._mapper.add_get_reference("spec", "/spec-name", + _get_ref_specification_type) assert self._name not in documenter_map documenter_map[self._name] = self + def _substitute(self, text: str) -> str: + if text: + return self._mapper.substitute(text) + return text + def get_section_reference(self) -> str: """ Returns the section reference. """ return get_reference(get_section_label(self.section, _SECTION_PREFIX)) @@ -142,14 +155,14 @@ class _Documenter: content.wrap( self.get_value_type_phrase("The attribute value", "shall", info["spec-type"])) - content.paste_and_add(info["description"]) + content.paste_and_add(self._substitute(info["description"])) def document_dict(self, content: SphinxContent, _variant: str, shall: str, info: Any) -> None: """ Documents an attribute set. """ if shall == "may": content.paste("The value may be a set of attributes.") - content.paste_and_add(info["description"]) + content.paste_and_add(self._substitute(info["description"])) has_explicit_attributes = len(info["attributes"]) > 0 if has_explicit_attributes: required_attributes = info["required-attributes"] @@ -184,20 +197,21 @@ class _Documenter: "The attribute value", "shall", info["generic-attributes"]["spec-type"]) content.paste(type_phrase) - content.paste_and_add(info["generic-attributes"]["description"]) + content.paste_and_add( + self._substitute(info["generic-attributes"]["description"])) def document_value(self, content: SphinxContent, variant: str, shall: str, info: Any) -> None: """ Documents a value. """ content.paste(self.get_value_type_phrase("The value", shall, variant)) - content.paste_and_add(info["description"]) + content.paste_and_add(self._substitute(info["description"])) def document_list(self, content: SphinxContent, _variant: str, shall: str, info: Any) -> None: """ Documents a list value. """ content.paste( self.get_list_phrase("The value", shall, info["spec-type"])) - content.paste_and_add(info["description"]) + content.paste_and_add(self._substitute(info["description"])) def document_none(self, content: SphinxContent, _variant: str, shall: str, _info: Any) -> None: @@ -334,9 +348,9 @@ def document(config: dict, item_cache: ItemCache) -> None: documenter_map = {} # type: _DocumenterMap root_item = item_cache[config["root-type"]] _create_str_documenter( - item_cache, "Name", - f"A string is a valid name if it matches with the ``{NAME.pattern}`` " - "regular expression.", documenter_map) + item_cache, "Name", "A string is a valid name if it matches with the " + f"``{NAME.pattern.replace('$', '$$')}`` regular expression.", + documenter_map) _create_str_documenter( item_cache, "UID", "The string shall be a valid absolute or relative item UID.", diff --git a/rtemsqual/tests/spec-doc/root.yml b/rtemsqual/tests/spec-doc/root.yml index 6be990a4..e96711e8 100644 --- a/rtemsqual/tests/spec-doc/root.yml +++ b/rtemsqual/tests/spec-doc/root.yml @@ -8,7 +8,8 @@ spec-example: null spec-info: bool: assert: true - description: null + description: | + A reference to ${.:/spec-name}. dict: attributes: type: diff --git a/rtemsqual/tests/test_specdoc.py b/rtemsqual/tests/test_specdoc.py index d07e2f1a..5ccd20f2 100644 --- a/rtemsqual/tests/test_specdoc.py +++ b/rtemsqual/tests/test_specdoc.py @@ -76,7 +76,7 @@ Root A value of this type shall be of one of the following variants: -* The value may be a boolean. +* The value may be a boolean. A reference to :ref:`SpecTypeRoot`. * The value may be a set of attributes. All explicitly defined attributes shall be specified. The following attributes are explicitly defined for this type: diff --git a/spec/spec/appl-config-option-constraints.yml b/spec/spec/appl-config-option-constraints.yml index 614d2e56..1e33835a 100644 --- a/spec/spec/appl-config-option-constraints.yml +++ b/spec/spec/appl-config-option-constraints.yml @@ -29,12 +29,12 @@ spec-info: description: | It shall be a list of constraints specific to this application configuration option. For general constraints, use a link with the - :ref:`SpecTypeConstraintLinkRole` to a constraint item. + ${constraint-role:/spec-name} to a constraint item. spec-type: requirement-text-list description: | This set of attributes defines application configuration option constraints. Additional constraints can be added through the links of - the item using the :ref:`SpecTypeConstraintLinkRole`. + the item using the ${constraint-role:/spec-name}. required-attributes: none spec-name: Application Configuration Option Constraint Set spec-type: appl-config-option-constraints diff --git a/spec/spec/appl-config-option.yml b/spec/spec/appl-config-option.yml index 2cb7d0e9..24af8d8d 100644 --- a/spec/spec/appl-config-option.yml +++ b/spec/spec/appl-config-option.yml @@ -24,9 +24,8 @@ spec-info: The description should be short and concentrate on the average case. All special cases, usage notes, constraints, error conditions, configuration dependencies, references, etc. should be described in - the notes. The - :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items have - an attribute for constraints. + the notes. The ${appl-config-option-value:/spec-name} items have an + attribute for constraints. spec-type: str index-entries: description: | diff --git a/spec/spec/build-action-set-test-state.yml b/spec/spec/build-action-set-test-state.yml index e07bd231..28aa0894 100644 --- a/spec/spec/build-action-set-test-state.yml +++ b/spec/spec/build-action-set-test-state.yml @@ -15,9 +15,10 @@ spec-info: generic-attributes: description: | The keys shall be test program names. The names shall correspond to - the name of a :ref:`SpecTypeBuildTestItemType` item. Due to the - processing order of items, there is no way to check if the name - specified by the attribute key is valid. + the name of a ${build-test-program:/spec-name} or + ${build-ada-test-program:/spec-name} item. Due to the processing order + of items, there is no way to check if the name specified by the + attribute key is valid. spec-type: build-test-state required-attributes: all spec-name: Build Option Set Test State Action diff --git a/spec/spec/build-action.yml b/spec/spec/build-action.yml index 535fde3a..462e03f6 100644 --- a/spec/spec/build-action.yml +++ b/spec/spec/build-action.yml @@ -14,9 +14,9 @@ spec-info: description: | It shall be the name of a test program. The action appends the action value to the ``CPPFLAGS`` of the test program. The name shall - correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` - item. Due to the processing order of items, there is no way to check - if the name specified by the attribute value is valid. + correspond to the name of a ${build-test-program:/spec-name} item. + Due to the processing order of items, there is no way to check if the + name specified by the attribute value is valid. spec-type: str assert-aligned: description: | @@ -150,7 +150,7 @@ spec-info: find-program: description: | The action tries to find the program specified by the action value. - Uses the ``${PATH}`` to find the program. Returns the result of the + Uses the ``$${PATH}`` to find the program. Returns the result of the find operation, e.g. a path to the program. spec-type: none find-tool: @@ -214,8 +214,8 @@ spec-info: spec-type: none substitute: description: | - The action Performs a ``${VARIABLE}`` substitution on the action - value. Use ``$$`` for a plain ``$`` character. + The action Performs a ``$${VARIABLE}`` substitution on the action + value. Use ``$$$$`` for a plain ``$$`` character. spec-type: none description: | This set of attributes specifies a build option action. diff --git a/spec/spec/build-ada-test-program.yml b/spec/spec/build-ada-test-program.yml index 92272940..66a470f7 100644 --- a/spec/spec/build-ada-test-program.yml +++ b/spec/spec/build-ada-test-program.yml @@ -62,10 +62,10 @@ spec-info: description: | This set of attributes specifies an Ada test program executable to build. Test programs may use additional objects provided by - :ref:`SpecTypeBuildObjectsItemType` items. Test programs have an - implicit ``enabled-by`` attribute value which is controlled by the option - action :ref:`set-test-state `. If the test - state is set to ``exclude``, then the test program is not built. + ${build-objects:/spec-name} items. Test programs have an implicit + ``enabled-by`` attribute value which is controlled by the option action + :ref:`set-test-state `. If the test state + is set to ``exclude``, then the test program is not built. required-attributes: all spec-name: Build Ada Test Program Item Type spec-type: build-ada-test-program diff --git a/spec/spec/build-config-file.yml b/spec/spec/build-config-file.yml index 238fd787..f99bbca9 100644 --- a/spec/spec/build-config-file.yml +++ b/spec/spec/build-config-file.yml @@ -16,10 +16,10 @@ spec-info: attributes: content: description: | - It shall be the content of the configuration file. A ${VARIABLE} + It shall be the content of the configuration file. A $${VARIABLE} substitution is performed during the configure command execution - using the variables of the configuration set. Use $$ for a plain $ - character. To have all variables from sibling items available for + using the variables of the configuration set. Use $$$$ for a plain + $$ character. To have all variables from sibling items available for substitution it is recommended to link them in the proper order. spec-type: str install-path: diff --git a/spec/spec/build-include.yml b/spec/spec/build-include.yml index c964906f..a3df76c5 100644 --- a/spec/spec/build-include.yml +++ b/spec/spec/build-include.yml @@ -13,13 +13,12 @@ spec-info: It shall be a path to header files. The path is used by the C preprocessor to search for header files. It succeeds the includes presented to the item by the build item context. For an - :ref:`SpecTypeBuildGroupItemType` item the includes are visible to all - items referenced by the group item. For :ref:`SpecTypeBuildBSPItemType`, - :ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`, - :ref:`SpecTypeBuildStartFileItemType`, and - :ref:`SpecTypeBuildTestProgramItemType` items the includes are only - visible to the sources specified by the item itself and they do not - propagate to referenced items. + ${build-group:/spec-name} item the includes are visible to all items + referenced by the group item. For ${build-bsp:/spec-name}, + ${build-objects:/spec-name}, ${build-library:/spec-name}, + ${build-start-file:/spec-name}, and ${build-test-program:/spec-name} + items the includes are only visible to the sources specified by the item + itself and they do not propagate to referenced items. spec-name: Build Include Path spec-type: build-include type: spec diff --git a/spec/spec/build-install-path.yml b/spec/spec/build-install-path.yml index ead261be..03c1a829 100644 --- a/spec/spec/build-install-path.yml +++ b/spec/spec/build-install-path.yml @@ -11,7 +11,7 @@ spec-info: none: null str: description: | - It shall be the installation path of a :ref:`SpecTypeBuildTarget`. + It shall be the installation path of a ${build-target:/spec-name}. spec-name: Build Install Path spec-type: build-install-path type: spec diff --git a/spec/spec/build-library.yml b/spec/spec/build-library.yml index 8f3e1c5e..8cfe1afe 100644 --- a/spec/spec/build-library.yml +++ b/spec/spec/build-library.yml @@ -42,8 +42,8 @@ spec-info: spec-type: build-target description: | This set of attributes specifies a static library. Library items may use - additional objects provided by :ref:`SpecTypeBuildObjectsItemType` items - through the build dependency links of the item. + additional objects provided by ${build-objects:/spec-name} items through + the build dependency links of the item. required-attributes: all spec-name: Build Library Item Type spec-type: build-library diff --git a/spec/spec/build-test-program.yml b/spec/spec/build-test-program.yml index 6afbcf28..29218cc0 100644 --- a/spec/spec/build-test-program.yml +++ b/spec/spec/build-test-program.yml @@ -53,10 +53,10 @@ spec-info: description: | This set of attributes specifies a test program executable to build. Test programs may use additional objects provided by - :ref:`SpecTypeBuildObjectsItemType` items. Test programs have an - implicit ``enabled-by`` attribute value which is controlled by the option - action :ref:`set-test-state `. If the test - state is set to ``exclude``, then the test program is not built. + ${build-objects:/spec-name} items. Test programs have an implicit + ``enabled-by`` attribute value which is controlled by the option action + :ref:`set-test-state `. If the test state + is set to ``exclude``, then the test program is not built. required-attributes: all spec-name: Build Test Program Item Type spec-type: build-test-program diff --git a/spec/spec/interface-container.yml b/spec/spec/interface-container.yml index 8106ea06..9f59b8ec 100644 --- a/spec/spec/interface-container.yml +++ b/spec/spec/interface-container.yml @@ -16,9 +16,9 @@ spec-info: attributes: {} description: | Items of this type specify an interface container. The item shall have - exactly one link with the :ref:`SpecTypeInterfacePlacementLinkRole` to an - :ref:`SpecTypeInterfaceDomainItemType` item. This link defines the - interface domain of the container. + exactly one link with the ${interface-placement:/spec-name} to an + ${interface-domain:/spec-name} item. This link defines the interface + domain of the container. required-attributes: all spec-name: Interface Container Item Type spec-type: interface-container diff --git a/spec/spec/interface-domain.yml b/spec/spec/interface-domain.yml index 327b05ba..0ea33efa 100644 --- a/spec/spec/interface-domain.yml +++ b/spec/spec/interface-domain.yml @@ -24,9 +24,9 @@ spec-info: spec-type: str description: | This set of attributes specifies an interface domain. Items of the types - :ref:`SpecTypeInterfaceContainerItemType` and - :ref:`SpecTypeInterfaceHeaderFileItemType` are placed into domains - through links with the :ref:`SpecTypeInterfacePlacementLinkRole`. + ${interface-container:/spec-name} and ${interface-header-file:/spec-name} + are placed into domains through links with the + ${interface-placement:/spec-name}. required-attributes: all spec-name: Interface Domain Item Type spec-type: interface-domain diff --git a/spec/spec/interface-forward-declaration.yml b/spec/spec/interface-forward-declaration.yml index c21da0a5..de6e1562 100644 --- a/spec/spec/interface-forward-declaration.yml +++ b/spec/spec/interface-forward-declaration.yml @@ -16,9 +16,9 @@ spec-info: attributes: {} description: | Items of this type specify a forward declaration. The item shall have - exactly one link with the :ref:`SpecTypeInterfaceTargetLinkRole` to an - :ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the - type declared by the forward declaration. + exactly one link with the ${interface-target:/spec-name} to an + ${interface-compound:/spec-name} item. This link defines the type + declared by the forward declaration. required-attributes: all spec-name: Interface Forward Declaration Item Type spec-type: interface-forward-declaration diff --git a/spec/spec/interface-header-file.yml b/spec/spec/interface-header-file.yml index 105e441d..f7965150 100644 --- a/spec/spec/interface-header-file.yml +++ b/spec/spec/interface-header-file.yml @@ -26,9 +26,9 @@ spec-info: spec-type: str description: | This set of attributes specifies a header file. The item shall have - exactly one link with the :ref:`SpecTypeInterfacePlacementLinkRole` to an - :ref:`SpecTypeInterfaceDomainItemType` item. This link defines the - interface domain of the header file. + exactly one link with the ${interface-placement:/spec-name} to an + ${interface-domain:/spec-name} item. This link defines the interface + domain of the header file. required-attributes: all spec-name: Interface Header File Item Type spec-type: interface-header-file diff --git a/spec/spec/requirement-validation.yml b/spec/spec/requirement-validation.yml index d021896f..453d6ca0 100644 --- a/spec/spec/requirement-validation.yml +++ b/spec/spec/requirement-validation.yml @@ -16,8 +16,7 @@ spec-info: attributes: method: description: | - Validation by test is done through :ref:`SpecTypeTestCaseItemType` - items. + Validation by test is done through ${test-case:/spec-name} items. spec-type: requirement-validation-method text: description: | @@ -28,7 +27,7 @@ spec-info: met, by analysing static properties of the software product. * *By inspection*: A statement shall be provided how the requirement - is met, by inspection of the :term:`source code`. + is met, by inspection of the ${/glos/term/sourcecode:/term}. * *By review of design*: A rationale shall be provided to demonstrate how the requirement is satisfied implicitly by the software design. @@ -36,7 +35,7 @@ spec-info: description: | This set of attributes provides a requirement validation evidence. The item shall have exactly one link to the validated requirement with the - :ref:`SpecTypeRequirementValidationLinkRole`. + ${requirement-validation-role:/spec-name}. required-attributes: all spec-name: Requirement Validation Item Type spec-type: requirement-validation -- cgit v1.2.3