[rtems-central commit] applconfig: Add document_option()

[Sebastian Huber]

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

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

applconfig: Add document_option()

---

 rtemsspec/applconfig.py            | 31 +++++++++++++++++++++++--------
 rtemsspec/tests/test_applconfig.py | 19 +++++++++++++++++--
 2 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/rtemsspec/applconfig.py b/rtemsspec/applconfig.py
index 1474a7f5..47bcb9d0 100644
--- a/rtemsspec/applconfig.py
+++ b/rtemsspec/applconfig.py
@@ -253,6 +253,27 @@ _OPTION_GENERATORS = {
 }
 
 
+def _document_option(item: Item, enabled: List[str],
+                     content: _ContentAdaptor) -> None:
+    option_type = item["appl-config-option-type"]
+    content.add_option_type(_OPTION_TYPES[option_type])
+    _OPTION_GENERATORS[option_type](content, item, option_type)
+    content.add_option_description(content.substitute(item["description"]))
+    content.add_option_notes(content.substitute(item["notes"]))
+    _generate_constraints(content, item, enabled)
+
+
+def document_option(item: Item, enabled: List[str],
+                    mapper: ItemMapper) -> SphinxContent:
+    """
+    Documents the option specified by the item using the item mapper and
+    enabled set.
+    """
+    adaptor = _SphinxContentAdaptor(mapper)
+    _document_option(item, enabled, adaptor)
+    return adaptor.content
+
+
 def _generate(group: Item, options: ItemMap, enabled: List[str],
               content: _ContentAdaptor) -> None:
     content.register_license_and_copyrights_of_item(group)
@@ -260,15 +281,9 @@ def _generate(group: Item, options: ItemMap, enabled: List[str],
                       content.substitute(group["description"]))
     for item in sorted(options.values(), key=lambda x: x["name"]):
         content.mapper.item = item
-        name = item["name"]
         content.register_license_and_copyrights_of_item(item)
-        content.add_option(item.uid, name, item["index-entries"])
-        option_type = item["appl-config-option-type"]
-        content.add_option_type(_OPTION_TYPES[option_type])
-        _OPTION_GENERATORS[option_type](content, item, option_type)
-        content.add_option_description(content.substitute(item["description"]))
-        content.add_option_notes(content.substitute(item["notes"]))
-        _generate_constraints(content, item, enabled)
+        content.add_option(item.uid, item["name"], item["index-entries"])
+        _document_option(item, enabled, content)
     content.add_licence_and_copyrights()
 
 
diff --git a/rtemsspec/tests/test_applconfig.py b/rtemsspec/tests/test_applconfig.py
index 5135cd5f..fc9172d2 100644
--- a/rtemsspec/tests/test_applconfig.py
+++ b/rtemsspec/tests/test_applconfig.py
@@ -26,8 +26,8 @@
 
 import os
 
-from rtemsspec.applconfig import generate
-from rtemsspec.items import ItemCache
+from rtemsspec.applconfig import document_option, generate
+from rtemsspec.items import ItemCache, ItemMapper
 from rtemsspec.tests.util import create_item_cache_config_and_copy_spec
 
 
@@ -723,3 +723,18 @@ description m
 /** @} */
 """
         assert content == src.read()
+        option_item = item_cache["/k"]
+        option_content = document_option(option_item, [],
+                                         ItemMapper(option_item))
+        assert str(option_content) == """.. rubric:: OPTION TYPE:
+
+This configuration option is an integer define.
+
+.. rubric:: DEFAULT VALUE:
+
+The default value is 1.
+
+.. rubric:: DESCRIPTION:
+
+description k
+"""