[rtems-central commit] interfacedoc: Add document_directive()

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri May  5 14:41:19 2023 +0200

interfacedoc: Add document_directive()

---

 rtemsspec/interfacedoc.py            | 15 +++++++++++++--
 rtemsspec/tests/test_interfacedoc.py | 16 +++++++++++++---
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/rtemsspec/interfacedoc.py b/rtemsspec/interfacedoc.py
index f7da0adf..880e4e63 100644
--- a/rtemsspec/interfacedoc.py
+++ b/rtemsspec/interfacedoc.py
@@ -127,7 +127,7 @@ def _add_definition(content: CContent, mapper: ItemMapper, item: Item,
         add_definition(content, mapper, item, definition)
 
 
-def _generate_directive(content: SphinxContent, mapper: SphinxInterfaceMapper,
+def _document_directive(content: SphinxContent, mapper: ItemMapper,
                         code_mapper: _CodeMapper, item: Item,
                         enabled: List[str]) -> None:
     content.wrap(mapper.substitute(item["brief"]))
@@ -175,6 +175,17 @@ def _generate_directive(content: SphinxContent, mapper: SphinxInterfaceMapper,
                          "The following constraints apply to this directive:")
 
 
+def document_directive(item: Item, enabled: List[str],
+                       mapper: ItemMapper) -> SphinxContent:
+    """
+    Documents the directive specified by the item using the item mapper and
+    enabled set.
+    """
+    content = SphinxContent()
+    _document_directive(content, mapper, _CodeMapper(item), item, enabled)
+    return content
+
+
 def _generate_directives(target: str, group: Item, group_uids: List[str],
                          items: List[Item], enabled: List[str]) -> None:
     content = SphinxContent()
@@ -201,7 +212,7 @@ def _generate_directives(target: str, group: Item, group_uids: List[str],
             content.add_index_entries([directive] + item["index-entries"])
             with content.section(directive,
                                  label=make_label(f"Interface {directive}")):
-                _generate_directive(content, mapper, code_mapper, item,
+                _document_directive(content, mapper, code_mapper, item,
                                     enabled)
     content.add_licence_and_copyrights()
     content.write(target)
diff --git a/rtemsspec/tests/test_interfacedoc.py b/rtemsspec/tests/test_interfacedoc.py
index 42c1a9c8..378af748 100644
--- a/rtemsspec/tests/test_interfacedoc.py
+++ b/rtemsspec/tests/test_interfacedoc.py
@@ -27,8 +27,8 @@
 import os
 import pytest
 
-from rtemsspec.interfacedoc import generate
-from rtemsspec.items import EmptyItemCache, ItemCache
+from rtemsspec.interfacedoc import document_directive, generate
+from rtemsspec.items import EmptyItemCache, ItemCache, ItemMapper
 from rtemsspec.tests.util import create_item_cache_config_and_copy_spec
 
 
@@ -50,7 +50,8 @@ def test_interfacedoc(tmpdir):
     item_cache_config = create_item_cache_config_and_copy_spec(
         tmpdir, "spec-interface", with_spec_types=True)
     config = {"enabled": [], "groups": [doc_config, doc_config_2]}
-    generate(config, ItemCache(item_cache_config))
+    item_cache = ItemCache(item_cache_config)
+    generate(config, item_cache)
 
     with open(introduction_rst, "r") as src:
         content = """.. SPDX-License-Identifier: CC-BY-SA-4.0
@@ -480,3 +481,12 @@ The following constraints apply to this directive:
 * Constraint A for :ref:`InterfaceFunction`.
 """
         assert content == src.read()
+        directive_item = item_cache["/func3"]
+        directive_content = document_directive(directive_item, [],
+                                               ItemMapper(directive_item))
+        assert str(directive_content) == """.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    void VoidFunction( void );
+"""