[rtems-central commit] interfacedoc: Only reference documented interfaces

Sebastian Huber sebh at rtems.org
Wed Feb 3 05:28:01 UTC 2021


Module:    rtems-central
Branch:    master
Commit:    775e495d8fedee2f8e73464135d669777b10fbe8
Changeset: http://git.rtems.org/rtems-central/commit/?id=775e495d8fedee2f8e73464135d669777b10fbe8

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Jan 15 16:34:06 2021 +0100

interfacedoc: Only reference documented interfaces

---

 rtemsspec/interfacedoc.py                | 27 +++++++++++++++++----------
 rtemsspec/tests/spec-interface/func4.yml |  3 ++-
 rtemsspec/tests/spec-interface/func5.yml | 27 +++++++++++++++++++++++++++
 rtemsspec/tests/spec-interface/ge.yml    | 12 ++++++++++++
 rtemsspec/tests/spec-interface/gf.yml    | 12 ++++++++++++
 rtemsspec/tests/test_interfacedoc.py     |  4 ++++
 6 files changed, 74 insertions(+), 11 deletions(-)

diff --git a/rtemsspec/interfacedoc.py b/rtemsspec/interfacedoc.py
index fcbdcf1..9820070 100644
--- a/rtemsspec/interfacedoc.py
+++ b/rtemsspec/interfacedoc.py
@@ -64,22 +64,26 @@ class _CodeMapper(ItemMapper):
                            _get_value_forward_declaration)
 
 
-def _get_value_function(ctx: ItemGetValueContext) -> Any:
-    return _get_reference(ctx.value[ctx.key])
-
-
 def _get_param(ctx: ItemGetValueContext) -> Any:
     return f"``{_sanitize_name(ctx.value[ctx.key])}``"
 
 
 class _Mapper(SphinxMapper):
-    def __init__(self, item: Item):
+    def __init__(self, item: Item, group_uids: List[str]):
         super().__init__(item)
-        self.add_get_value("interface/function:/name", _get_value_function)
-        self.add_get_value("interface/macro:/name", _get_value_function)
+        self._group_uids = set(group_uids)
+        self.add_get_value("interface/function:/name", self._get_function)
+        self.add_get_value("interface/macro:/name", self._get_function)
         self.add_get_value("interface/function:/params/name", _get_param)
         self.add_get_value("interface/macro:/params/name", _get_param)
 
+    def _get_function(self, ctx: ItemGetValueContext) -> Any:
+        name = ctx.value[ctx.key]
+        for group in ctx.item.parents("interface-ingroup"):
+            if group.uid in self._group_uids:
+                return _get_reference(name)
+        return f":c:func:`{name}`"
+
 
 def _generate_introduction(target: str, group: Item,
                            items: List[Item]) -> None:
@@ -191,7 +195,8 @@ def _generate_directive(content: SphinxContent, mapper: _Mapper,
         content.wrap(mapper.substitute(item["notes"]))
 
 
-def _generate_directives(target: str, group: Item, items: List[Item]) -> None:
+def _generate_directives(target: str, group: Item, group_uids: List[str],
+                         items: List[Item]) -> None:
     content = SphinxContent()
     content.register_license_and_copyrights_of_item(group)
     content.add_automatically_generated_warning()
@@ -207,7 +212,7 @@ def _generate_directives(target: str, group: Item, items: List[Item]) -> None:
             content.register_license_and_copyrights_of_item(item)
             name = item["name"]
             code_mapper = _CodeMapper(item)
-            mapper = _Mapper(item)
+            mapper = _Mapper(item, group_uids)
             content.add(f".. Generated from spec:{item.uid}")
             with content.directive("raw", "latex"):
                 content.add("\\clearpage")
@@ -234,6 +239,7 @@ def generate(config: list, item_cache: ItemCache) -> None:
     :param config: A dictionary with configuration entries.
     :param item_cache: The specification item cache containing the interfaces.
     """
+    group_uids = [doc_config["group"] for doc_config in config]
     for doc_config in config:
         items = []  # type: List[Item]
         group = item_cache[doc_config["group"]]
@@ -244,4 +250,5 @@ def generate(config: list, item_cache: ItemCache) -> None:
         items.sort(key=functools.partial(
             _directive_key, list(group.parents("placement-order"))))
         _generate_introduction(doc_config["introduction-target"], group, items)
-        _generate_directives(doc_config["directives-target"], group, items)
+        _generate_directives(doc_config["directives-target"], group,
+                             group_uids, items)
diff --git a/rtemsspec/tests/spec-interface/func4.yml b/rtemsspec/tests/spec-interface/func4.yml
index a463495..193329d 100644
--- a/rtemsspec/tests/spec-interface/func4.yml
+++ b/rtemsspec/tests/spec-interface/func4.yml
@@ -25,7 +25,8 @@ links:
 - role: interface-ingroup
   uid: gb
 name: VeryLongTypeFunction
-notes: null
+notes: |
+  See also ${func5:/name}.
 params: []
 return:
   return: This function returns an object with a very long type.
diff --git a/rtemsspec/tests/spec-interface/func5.yml b/rtemsspec/tests/spec-interface/func5.yml
new file mode 100644
index 0000000..10caf42
--- /dev/null
+++ b/rtemsspec/tests/spec-interface/func5.yml
@@ -0,0 +1,27 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: null
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: null
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-ingroup
+  uid: ge
+- role: interface-ingroup
+  uid: gf
+name: Func5
+notes: null
+params: []
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/rtemsspec/tests/spec-interface/ge.yml b/rtemsspec/tests/spec-interface/ge.yml
new file mode 100644
index 0000000..7c94414
--- /dev/null
+++ b/rtemsspec/tests/spec-interface/ge.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: Group E brief description.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+description: Group E description.
+enabled-by: true
+identifier: GroupE
+index-entries: []
+interface-type: group
+links: []
+name: Group E
+type: interface
diff --git a/rtemsspec/tests/spec-interface/gf.yml b/rtemsspec/tests/spec-interface/gf.yml
new file mode 100644
index 0000000..77ea9b5
--- /dev/null
+++ b/rtemsspec/tests/spec-interface/gf.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: Group F brief description.
+copyrights:
+- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+description: Group F description.
+enabled-by: true
+identifier: GroupF
+index-entries: []
+interface-type: group
+links: []
+name: Group F
+type: interface
diff --git a/rtemsspec/tests/test_interfacedoc.py b/rtemsspec/tests/test_interfacedoc.py
index 070bf6a..b060cf0 100644
--- a/rtemsspec/tests/test_interfacedoc.py
+++ b/rtemsspec/tests/test_interfacedoc.py
@@ -158,6 +158,10 @@ Function brief description with very long return type.
 
 This function returns an object with a very long type.
 
+.. rubric:: NOTES:
+
+See also :c:func:`Func5`.
+
 .. Generated from spec:/func2
 
 .. raw:: latex



More information about the vc mailing list