summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-07-16 12:16:19 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2020-09-18 13:17:54 +0200
commit87b54577fac555907ea68cf8008602bd65157d25 (patch)
tree542ef3b2c4504442a2190b075c62f0e4969aa3d0
parent795687417ff537fdbd533e62e38377ad920d12fa (diff)
downloadrtems-central-87b54577fac555907ea68cf8008602bd65157d25.tar.bz2
specdoc: Make label prefix configurable
-rw-r--r--config.yml1
-rw-r--r--rtemsspec/specdoc.py39
-rw-r--r--rtemsspec/tests/test_specdoc.py1
3 files changed, 22 insertions, 19 deletions
diff --git a/config.yml b/config.yml
index debeac7..cf188b0 100644
--- a/config.yml
+++ b/config.yml
@@ -100,3 +100,4 @@ spec-verification:
spec-documentation:
root-type: /spec/root
doc-target: modules/rtems-docs/eng/req/items.rst
+ label-prefix: SpecType
diff --git a/rtemsspec/specdoc.py b/rtemsspec/specdoc.py
index b736867..823a7d5 100644
--- a/rtemsspec/specdoc.py
+++ b/rtemsspec/specdoc.py
@@ -57,8 +57,6 @@ _MANDATORY_ATTRIBUTES = {
"they are all optional.",
}
-_SPEC_TYPE_PREFIX = "SpecType"
-
def _a_or_an(value: str) -> str:
if value[0].lower() in ["a", "e", "i", "o", "u"]:
@@ -66,10 +64,6 @@ def _a_or_an(value: str) -> str:
return "a"
-def _get_ref_specification_type(ctx: ItemGetValueContext) -> Any:
- return get_reference(_SPEC_TYPE_PREFIX + get_label(ctx.value[ctx.key]))
-
-
class _AssertContext:
""" This class provides a context to document assert expressions. """
def __init__(self, content: SphinxContent, ops: Dict[str, Any]):
@@ -260,7 +254,8 @@ def _maybe_document_assert(content: SphinxContent, type_info: Any) -> None:
class _Documenter:
# pylint: disable=too-many-instance-attributes
- def __init__(self, item: Item, documenter_map: _DocumenterMap):
+ def __init__(self, item: Item, documenter_map: _DocumenterMap,
+ config: dict):
self._name = item["spec-type"]
self.section = item["spec-name"]
self._description = item["spec-description"]
@@ -268,12 +263,17 @@ class _Documenter:
self._item = item
self._documenter_map = documenter_map
self.used_by = set() # type: Set[str]
+ self._label_prefix = config["label-prefix"]
self._mapper = SphinxMapper(item)
self._mapper.add_get_value("spec:/spec-name",
- _get_ref_specification_type)
+ self._get_ref_specification_type)
assert self._name not in documenter_map
documenter_map[self._name] = self
+ def _get_ref_specification_type(self, ctx: ItemGetValueContext) -> Any:
+ return get_reference(self._label_prefix +
+ get_label(ctx.value[ctx.key]))
+
def _substitute(self, text: str) -> str:
if text:
return self._mapper.substitute(text)
@@ -281,7 +281,7 @@ class _Documenter:
def get_section_reference(self) -> str:
""" Returns the section reference. """
- return get_reference(_SPEC_TYPE_PREFIX + get_label(self.section))
+ return get_reference(self._label_prefix + get_label(self.section))
def get_a_section_reference(self) -> str:
""" Returns a section reference. """
@@ -434,7 +434,7 @@ class _Documenter:
if self.get_list_element_type():
return
content.register_license_and_copyrights_of_item(self._item)
- with content.section(self.section, _SPEC_TYPE_PREFIX):
+ with content.section(self.section, self._label_prefix):
last = content.lines[-1]
self._add_description(content)
if len(self._info_map) == 1:
@@ -498,15 +498,16 @@ _DOCUMENT = {
}
-def _gather_item_documenters(item: Item,
- documenter_map: _DocumenterMap) -> None:
+def _gather_item_documenters(item: Item, documenter_map: _DocumenterMap,
+ config: dict) -> None:
for link in item.links_to_children():
if link.role == "spec-member":
- _Documenter(link.item, documenter_map)
+ _Documenter(link.item, documenter_map, config)
def _create_str_documenter(item_cache: ItemCache, name: str, description: str,
- documenter_map: _DocumenterMap) -> None:
+ documenter_map: _DocumenterMap,
+ config: dict) -> None:
type_name = name.lower()
_Documenter(
Item(
@@ -530,7 +531,7 @@ def _create_str_documenter(item_cache: ItemCache, name: str, description: str,
name,
"spec-type":
type_name,
- }), documenter_map)
+ }), documenter_map, config)
def document(config: dict, item_cache: ItemCache) -> None:
@@ -545,13 +546,13 @@ def document(config: dict, item_cache: ItemCache) -> None:
_create_str_documenter(
item_cache, "Name", "A string is a valid name if it matches with the "
f"``{NAME.pattern.replace('$', '$$')}`` regular expression.",
- documenter_map)
+ documenter_map, config)
_create_str_documenter(
item_cache, "UID",
"The string shall be a valid absolute or relative item UID.",
- documenter_map)
- root_documenter = _Documenter(root_item, documenter_map)
- _gather_item_documenters(root_item, documenter_map)
+ documenter_map, config)
+ root_documenter = _Documenter(root_item, documenter_map, config)
+ _gather_item_documenters(root_item, documenter_map, config)
content = SphinxContent()
content.add_automatically_generated_warning()
for documenter in documenter_map.values():
diff --git a/rtemsspec/tests/test_specdoc.py b/rtemsspec/tests/test_specdoc.py
index 199be3e..0a3d294 100644
--- a/rtemsspec/tests/test_specdoc.py
+++ b/rtemsspec/tests/test_specdoc.py
@@ -41,6 +41,7 @@ def test_document(tmpdir):
config = {
"root-type": "/root",
"doc-target": doc_target,
+ "label-prefix": "SpecType",
}
document(config, item_cache)
with open(doc_target, "r") as src: