[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