[rtems-central commit] content: Add interface group references

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Jan 20 06:49:53 2021 +0100

content: Add interface group references

---

 rtemsspec/applconfig.py                 | 3 ++-
 rtemsspec/content.py                    | 5 +++++
 rtemsspec/interface.py                  | 4 +++-
 rtemsspec/interfacedoc.py               | 8 +++++++-
 rtemsspec/tests/spec-interface/func.yml | 4 ++--
 rtemsspec/tests/test_interface.py       | 4 ++--
 rtemsspec/tests/test_interfacedoc.py    | 3 ++-
 7 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/rtemsspec/applconfig.py b/rtemsspec/applconfig.py
index 6e3691c..c25503e 100644
--- a/rtemsspec/applconfig.py
+++ b/rtemsspec/applconfig.py
@@ -28,7 +28,7 @@ import copy
 from typing import Any, Dict, List, Optional
 
 from rtemsspec.content import CContent, get_value_double_colon, \
-    get_value_doxygen_function, get_value_hash
+    get_value_doxygen_function, get_value_doxygen_group, get_value_hash
 from rtemsspec.sphinxcontent import SphinxContent, SphinxMapper
 from rtemsspec.items import EmptyItem, Item, ItemCache, ItemGetValueContext, \
     ItemMapper
@@ -449,6 +449,7 @@ def _add_doxygen_get_values(mapper: ItemMapper) -> None:
     mapper.add_get_value("interface/define:/name", get_value_hash)
     mapper.add_get_value("interface/function:/name",
                          get_value_doxygen_function)
+    mapper.add_get_value("interface/group:/name", get_value_doxygen_group)
     mapper.add_get_value("interface/macro:/name", get_value_doxygen_function)
     mapper.add_get_value("interface/struct:/name", get_value_double_colon)
     mapper.add_get_value("interface/typedef:/name", get_value_double_colon)
diff --git a/rtemsspec/content.py b/rtemsspec/content.py
index f372958..616a7a1 100644
--- a/rtemsspec/content.py
+++ b/rtemsspec/content.py
@@ -967,6 +967,11 @@ def get_value_doxygen_function(ctx: ItemGetValueContext) -> Any:
     return f"{ctx.value[ctx.key]}()"
 
 
+def get_value_doxygen_group(ctx: ItemGetValueContext) -> Any:
+    """ Gets a value as a group reference for Doxygen markup. """
+    return f"@ref {ctx.value['identifier']}"
+
+
 def get_value_double_colon(ctx: ItemGetValueContext) -> Any:
     """ Gets a value with a :: prefix. """
     return f"::{ctx.value[ctx.key]}"
diff --git a/rtemsspec/interface.py b/rtemsspec/interface.py
index d796e2e..7adf63a 100644
--- a/rtemsspec/interface.py
+++ b/rtemsspec/interface.py
@@ -30,7 +30,7 @@ from typing import Any, Callable, Dict, Iterator, List, Union, Set
 
 from rtemsspec.content import CContent, CInclude, enabled_by_to_exp, \
     ExpressionMapper, get_value_double_colon, get_value_doxygen_function, \
-    get_value_hash
+    get_value_doxygen_group, get_value_hash
 from rtemsspec.items import Item, ItemCache, ItemGetValueContext, \
     ItemGetValueMap, ItemMapper
 
@@ -82,6 +82,8 @@ class _InterfaceMapper(ItemMapper):
                            get_value_double_colon)
         self.add_get_value("interface/define/doc:/name", get_value_hash)
         self.add_get_value("interface/enum/doc:/name", get_value_hash)
+        self.add_get_value("interface/group/doc:/name",
+                           get_value_doxygen_group)
         self.add_get_value("interface/macro/doc:/name",
                            get_value_doxygen_function)
         self.add_get_value("interface/macro/doc:/params/name",
diff --git a/rtemsspec/interfacedoc.py b/rtemsspec/interfacedoc.py
index 9820070..59a5199 100644
--- a/rtemsspec/interfacedoc.py
+++ b/rtemsspec/interfacedoc.py
@@ -73,8 +73,9 @@ class _Mapper(SphinxMapper):
         super().__init__(item)
         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/group:/name", self._get_group)
+        self.add_get_value("interface/macro:/name", self._get_function)
         self.add_get_value("interface/macro:/params/name", _get_param)
 
     def _get_function(self, ctx: ItemGetValueContext) -> Any:
@@ -84,6 +85,11 @@ class _Mapper(SphinxMapper):
                 return _get_reference(name)
         return f":c:func:`{name}`"
 
+    def _get_group(self, ctx: ItemGetValueContext) -> Any:
+        if ctx.item.uid in self._group_uids:
+            return get_reference(ctx.value["identifier"])
+        return ctx.value[ctx.key]
+
 
 def _generate_introduction(target: str, group: Item,
                            items: List[Item]) -> None:
diff --git a/rtemsspec/tests/spec-interface/func.yml b/rtemsspec/tests/spec-interface/func.yml
index 25a23b3..422a3a7 100644
--- a/rtemsspec/tests/spec-interface/func.yml
+++ b/rtemsspec/tests/spec-interface/func.yml
@@ -16,8 +16,8 @@ definition:
 description: |
   Function description.  References to ${func2:/name}, ${td:/name},
   ${enum:/name}, ${define:/name}, ${macro:/name}, ${var:/name},
-  ${enumerator-0:/name}, ${s:/name}, ${option:/name}, and ${option:/type}.
-  Second parameter is ${.:/params[1]/name}.
+  ${enumerator-0:/name}, ${s:/name}, ${option:/name}, ${option:/type},
+  ${ga:/name}, and ${gf:/name}.  Second parameter is ${.:/params[1]/name}.
 
   .. code-block:
 
diff --git a/rtemsspec/tests/test_interface.py b/rtemsspec/tests/test_interface.py
index 0519eb2..2ca9623 100644
--- a/rtemsspec/tests/test_interface.py
+++ b/rtemsspec/tests/test_interface.py
@@ -208,8 +208,8 @@ typedef enum EnumB {
  * @brief Function brief description.
  *
  * Function description.  References to VeryLongFunction(), ::Integer, #Enum,
- * #DEFINE, VERY_LONG_MACRO(), #Variable, ::ENUMERATOR_0, Struct, #a, and
- * interface. Second parameter is ``Param1``.
+ * #DEFINE, VERY_LONG_MACRO(), #Variable, ::ENUMERATOR_0, Struct, #a,
+ * interface, @ref GroupA, and @ref GroupF.  Second parameter is ``Param1``.
  *
  * @code
  * these two lines
diff --git a/rtemsspec/tests/test_interfacedoc.py b/rtemsspec/tests/test_interfacedoc.py
index b060cf0..0ead530 100644
--- a/rtemsspec/tests/test_interfacedoc.py
+++ b/rtemsspec/tests/test_interfacedoc.py
@@ -454,7 +454,8 @@ Function brief description.
 Function description.  References to :ref:`InterfaceVeryLongFunction`,
 :c:type:`Integer`, :c:type:`Enum`, :c:macro:`DEFINE`,
 :ref:`InterfaceVERYLONGMACRO`, Variable, :c:macro:`ENUMERATOR_0`,
-:c:type:`Struct`, :ref:`a`, and interface. Second parameter is ``Param1``.
+:c:type:`Struct`, :ref:`a`, interface, :ref:`GroupA`, and Group F.  Second
+parameter is ``Param1``.
 
 .. code-block: