[rtems-central commit] specdoc: Add pattern to ignore types
Sebastian Huber
sebh at rtems.org
Fri Sep 18 11:31:55 UTC 2020
Module: rtems-central
Branch: master
Commit: 4f28d90a474c095deb55c6db85e9da183084aac1
Changeset: http://git.rtems.org/rtems-central/commit/?id=4f28d90a474c095deb55c6db85e9da183084aac1
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Jul 29 14:12:06 2020 +0200
specdoc: Add pattern to ignore types
---
config.yml | 1 +
rtemsspec/specdoc.py | 45 ++++++++++++++++++++---------------------
rtemsspec/tests/spec-doc/f.yml | 25 +++++++++++++++++++++++
rtemsspec/tests/test_specdoc.py | 2 ++
4 files changed, 50 insertions(+), 23 deletions(-)
diff --git a/config.yml b/config.yml
index 5028e75..70004ba 100644
--- a/config.yml
+++ b/config.yml
@@ -103,6 +103,7 @@ spec-documentation:
hierarchy-subsection-name: Specification Item Hierarchy
hierarchy-text: |
The specification item types have the following hierarchy:
+ ignore: '^$'
item-types-subsection-name: Specification Item Types
root-type: /spec/root
section-label-prefix: ReqEng
diff --git a/rtemsspec/specdoc.py b/rtemsspec/specdoc.py
index 94c7de3..48e00f9 100644
--- a/rtemsspec/specdoc.py
+++ b/rtemsspec/specdoc.py
@@ -24,7 +24,8 @@
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
-from typing import Any, Dict, Iterator, List, Optional, Set, Tuple
+import re
+from typing import Any, Dict, Iterator, List, Optional, Pattern, Set, Tuple
from rtemsspec.sphinxcontent import get_reference, get_label, \
SphinxContent, SphinxMapper
@@ -316,12 +317,13 @@ class _Documenter:
return (f"{value} {shall} be "
f"{documenter.get_a_section_reference()}.")
- def refinements(self) -> Iterator["_Documenter"]:
+ def refinements(self, ignore: Pattern[Any]) -> Iterator["_Documenter"]:
""" Yields the refinements of this type. """
- refinements = set(self._documenter_map[link.item["spec-type"]]
- for link in self._item.links_to_children()
- if link.role == "spec-refinement")
- yield from sorted(refinements, key=lambda x: x.section)
+ refinement_set = set(
+ self._documenter_map[child["spec-type"]]
+ for child in self._item.children("spec-refinement")
+ if ignore.search(child["spec-type"]) is None)
+ yield from sorted(refinement_set, key=lambda x: x.section)
def refines(self) -> Iterator[Tuple["_Documenter", str, str]]:
""" Yields the types refined by type. """
@@ -331,11 +333,11 @@ class _Documenter:
if link.role == "spec-refinement"]
yield from sorted(refines, key=lambda x: x[0].section)
- def hierarchy(self, content: SphinxContent) -> None:
+ def hierarchy(self, content: SphinxContent, ignore) -> None:
""" Documents the item type hierarchy. """
with content.list_item(self.get_section_reference()):
- for refinement in self.refinements():
- refinement.hierarchy(content)
+ for refinement in self.refinements(ignore):
+ refinement.hierarchy(content, ignore)
def _document_attributes(self, content: SphinxContent,
attributes: Any) -> None:
@@ -431,6 +433,7 @@ class _Documenter:
def document(self,
content: SphinxContent,
+ ignore: Pattern[Any],
names: Optional[Set[str]] = None) -> None:
""" Document this type. """
if self.get_list_element_type():
@@ -453,7 +456,7 @@ class _Documenter:
self._info_map[key])
content.add_list([
refinement.get_section_reference()
- for refinement in self.refinements()
+ for refinement in self.refinements(ignore)
], "This type is refined by the following types:")
content.add_list(sorted(self.used_by),
"This type is used by the following types:")
@@ -464,8 +467,8 @@ class _Documenter:
content.add(example)
if names:
names.remove(self._name)
- for refinement in self.refinements():
- refinement.document(content, names)
+ for refinement in self.refinements(ignore):
+ refinement.document(content, ignore, names)
def _add_used_by(self, type_name: str) -> None:
if type_name not in _PRIMITIVE_TYPES:
@@ -500,13 +503,6 @@ _DOCUMENT = {
}
-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, config)
-
-
def _create_str_documenter(item_cache: ItemCache, name: str, description: str,
documenter_map: _DocumenterMap,
config: dict) -> None:
@@ -554,7 +550,10 @@ def document(config: dict, item_cache: ItemCache) -> None:
"The string shall be a valid absolute or relative item UID.",
documenter_map, config)
root_documenter = _Documenter(root_item, documenter_map, config)
- _gather_item_documenters(root_item, documenter_map, config)
+ ignore = re.compile(config["ignore"])
+ for member in root_item.children("spec-member"):
+ if ignore.search(member["spec-type"]) is None:
+ _Documenter(member, documenter_map, config)
content = SphinxContent()
content.add_automatically_generated_warning()
for documenter in documenter_map.values():
@@ -564,12 +563,12 @@ def document(config: dict, item_cache: ItemCache) -> None:
with content.section(config["section-name"]):
with content.section(config["hierarchy-subsection-name"]):
content.add(config["hierarchy-text"])
- root_documenter.hierarchy(content)
+ root_documenter.hierarchy(content, ignore)
with content.section(config["item-types-subsection-name"]):
- root_documenter.document(content, documenter_names)
+ root_documenter.document(content, ignore, documenter_names)
with content.section(config["value-types-subsection-name"]):
documenters = [documenter_map[name] for name in documenter_names]
for documenter in sorted(documenters, key=lambda x: x.section):
- documenter.document(content)
+ documenter.document(content, ignore)
content.add_licence_and_copyrights()
content.write(config["doc-target"])
diff --git a/rtemsspec/tests/spec-doc/f.yml b/rtemsspec/tests/spec-doc/f.yml
new file mode 100644
index 0000000..37b8161
--- /dev/null
+++ b/rtemsspec/tests/spec-doc/f.yml
@@ -0,0 +1,25 @@
+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
+spec-description: null
+spec-example: null
+spec-info:
+ dict:
+ attributes:
+ f1:
+ description: null
+ spec-type: name
+ f2:
+ description: null
+ spec-type: none
+ description: null
+ mandatory-attributes:
+ - f1
+ - f2
+spec-name: F
+spec-type: f
+type: spec
diff --git a/rtemsspec/tests/test_specdoc.py b/rtemsspec/tests/test_specdoc.py
index 77fbbbd..8b4eccb 100644
--- a/rtemsspec/tests/test_specdoc.py
+++ b/rtemsspec/tests/test_specdoc.py
@@ -45,6 +45,8 @@ def test_document(tmpdir):
"Specification Item Hierarchy",
"hierarchy-text":
"The specification item types have the following hierarchy:",
+ "ignore":
+ "^f$",
"item-types-subsection-name":
"Specification Item Types",
"label-prefix":
More information about the vc
mailing list