[rtems-central commit] applconfig: Use rubric instead of definition list

Sebastian Huber sebh at rtems.org
Wed Nov 17 08:07:50 UTC 2021


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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Mon Nov 15 18:58:27 2021 +0100

applconfig: Use rubric instead of definition list

Generalize value constraints to constraints.  For direcives and
application configuration options use the same rubric order.

---

 rtemsspec/applconfig.py            |  80 +++++-----
 rtemsspec/tests/test_applconfig.py | 301 ++++++++++++++++++++-----------------
 2 files changed, 202 insertions(+), 179 deletions(-)

diff --git a/rtemsspec/applconfig.py b/rtemsspec/applconfig.py
index 916682f..70030b6 100644
--- a/rtemsspec/applconfig.py
+++ b/rtemsspec/applconfig.py
@@ -28,7 +28,8 @@ from typing import Any, Dict, List, Optional
 
 from rtemsspec.content import Content, CContent, get_value_double_colon, \
     get_value_doxygen_function, get_value_doxygen_group, get_value_hash
-from rtemsspec.sphinxcontent import SphinxContent, SphinxInterfaceMapper
+from rtemsspec.sphinxcontent import GenericContent, SphinxContent, \
+    SphinxInterfaceMapper
 from rtemsspec.items import EmptyItem, Item, ItemCache, ItemGetValueContext, \
     ItemMapper
 
@@ -74,6 +75,18 @@ class _ContentAdaptor:
         self.content.add_header(name, level=2)
         self.content.add(description)
 
+    def _add_rubric(self,
+                    name: str,
+                    text: GenericContent,
+                    wrap: bool = False) -> None:
+        if not text:
+            return
+        self.content.add(f".. rubric:: {name}:")
+        if wrap:
+            self.content.wrap(text)
+        else:
+            self.content.add(text)
+
     def add_option(self, uid: str, name: str,
                    index_entries: List[str]) -> None:
         """ Adds an option. """
@@ -81,35 +94,31 @@ class _ContentAdaptor:
         self.content.add_index_entries([name] + index_entries)
         self.content.add_label(name)
         self.content.add_header(name, level=3)
-        self.content.add_definition_item("CONSTANT:", f"``{name}``")
+        self._add_rubric("CONSTANT", f"``{name}``")
 
     def add_option_type(self, option_type: str) -> None:
         """ Adds an option type. """
-        self.content.add_definition_item("OPTION TYPE:", option_type)
+        self._add_rubric("OPTION TYPE", option_type)
 
     def add_option_default_value(self, value: str) -> None:
         """ Adds an option default value. """
-        self.content.add_definition_item("DEFAULT VALUE:", value)
+        self._add_rubric("DEFAULT VALUE", value)
 
     def add_option_default_config(self, config: str) -> None:
         """ Adds an option default configuration. """
-        self.content.add_definition_item("DEFAULT CONFIGURATION:", config)
-
-    def add_option_value_constraints(self, lines: List[str]) -> None:
-        """ Adds a option value constraints. """
-        self.content.add_definition_item("VALUE CONSTRAINTS:",
-                                         lines,
-                                         wrap=True)
+        self._add_rubric("DEFAULT CONFIGURATION", config)
 
     def add_option_description(self, description: str) -> None:
         """ Adds a option description. """
-        self.content.add_definition_item("DESCRIPTION:", description)
+        self._add_rubric("DESCRIPTION", description)
 
-    def add_option_notes(self, notes: Optional[str]) -> None:
+    def add_option_notes(self, notes: str) -> None:
         """ Adds option notes. """
-        if not notes:
-            notes = "None."
-        self.content.add_definition_item("NOTES:", notes)
+        self._add_rubric("NOTES", notes)
+
+    def add_option_constraints(self, lines: List[str]) -> None:
+        """ Adds a option value constraints. """
+        self._add_rubric("CONSTRAINTS", lines, wrap=True)
 
     def add_licence_and_copyrights(self) -> None:
         """ Adds the license and copyrights. """
@@ -141,7 +150,7 @@ class _DoxygenContentAdaptor(_ContentAdaptor):
         self._option_type = ""
         self._default_value = ""
         self._default_config = ""
-        self._value_constraints = []  # type: List[str]
+        self._notes = ""
         self._description = ""
 
     def add_group(self, uid: str, name: str, description: str) -> None:
@@ -167,21 +176,20 @@ class _DoxygenContentAdaptor(_ContentAdaptor):
     def add_option_default_config(self, config: str) -> None:
         self._default_config = config
 
-    def add_option_value_constraints(self, lines: List[str]) -> None:
-        self._value_constraints = lines
-
     def add_option_description(self, description: str) -> None:
         self._description = description
 
-    def add_option_notes(self, notes: Optional[str]) -> None:
+    def add_option_notes(self, notes: str) -> None:
+        self._notes = notes
+
+    def add_option_constraints(self, lines: List[str]) -> None:
         self.content.add_brief_description(self._option_type)
         self.content.doxyfy(self._description)
         self.content.add_paragraph("Default Value", self._default_value)
         self.content.add_paragraph("Default Configuration",
                                    self._default_config)
-        self.content.add_paragraph("Value Constraints",
-                                   self._value_constraints)
-        self.content.add_paragraph("Notes", notes)
+        self.content.add_paragraph("Constraints", lines)
+        self.content.add_paragraph("Notes", self._notes)
         self.content.close_comment_block()
         self.content.append(f"#define {self._name}")
         self._reset()
@@ -200,27 +208,21 @@ def _get_constraints(content: _ContentAdaptor, item: Item) -> List[str]:
     constraints = []  # type: List[str]
     for parent in item.parents("constraint"):
         content.register_license_and_copyrights_of_item(parent)
-        constraints.append(content.substitute(parent["text"]))
+        constraints.append(
+            content.substitute(parent["text"]).replace(
+                "application configuration option", "configuration option"))
     return constraints
 
 
-_THE_VALUE = "The value of the application configuration option"
-
-
-def _generate_constraint(content: _ContentAdaptor, item: Item) -> None:
+def _generate_constraints(content: _ContentAdaptor, item: Item) -> None:
     constraints = _get_constraints(content, item)
     if len(constraints) > 1:
         constraint_list = Content("BSD-2-Clause", False)
-        prologue = """The value of this configuration option shall satisfy all
-of the following constraints:"""
-        constraint_list.add_list([
-            constraint.replace(_THE_VALUE, "It") for constraint in constraints
-        ], prologue)
+        prologue = ("The following constraints apply "
+                    "to this configuration option:")
+        constraint_list.add_list(constraints, prologue)
         constraints = constraint_list.lines
-    elif constraints:
-        constraints[0] = constraints[0].replace(
-            _THE_VALUE, "The value of this configuration option")
-    content.add_option_value_constraints(constraints)
+    content.add_option_constraints(constraints)
 
 
 def _generate_initializer_or_integer(content: _ContentAdaptor, item: Item,
@@ -229,7 +231,6 @@ def _generate_initializer_or_integer(content: _ContentAdaptor, item: Item,
     if not isinstance(default_value, str) or " " not in default_value:
         default_value = f"The default value is {default_value}."
     content.add_option_default_value(content.substitute(default_value))
-    _generate_constraint(content, item)
 
 
 _OPTION_GENERATORS = {
@@ -254,6 +255,7 @@ def _generate(group: Item, options: ItemMap, content: _ContentAdaptor) -> None:
         _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)
     content.add_licence_and_copyrights()
 
 
diff --git a/rtemsspec/tests/test_applconfig.py b/rtemsspec/tests/test_applconfig.py
index c2ebd77..c88f537 100644
--- a/rtemsspec/tests/test_applconfig.py
+++ b/rtemsspec/tests/test_applconfig.py
@@ -80,46 +80,51 @@ description
 a
 -
 
-CONSTANT:
-    ``a``
+.. rubric:: CONSTANT:
 
-OPTION TYPE:
-    This configuration option is a boolean feature define.
+``a``
 
-DEFAULT CONFIGURATION:
-    default a
+.. rubric:: OPTION TYPE:
 
-DESCRIPTION:
-    description a
+This configuration option is a boolean feature define.
 
-NOTES:
-    notes a
+.. rubric:: DEFAULT CONFIGURATION:
 
-    references:
+default a
 
-    * :ref:`b`
+.. rubric:: DESCRIPTION:
 
-    * :ref:`SphinxRefUnspecGroup`
+description a
 
-    * Unspec Group 2
+.. rubric:: NOTES:
 
-    * `Unspec Group 3 <unspec-group-3.html>`_
+notes a
 
-    * :ref:`unspec_func() <SphinxRefUnspecFunc>`
+references:
 
-    * :c:func:`func`
+* :ref:`b`
 
-    * :c:type:`td`
+* :ref:`SphinxRefUnspecGroup`
 
-    * :c:macro:`DEFINE`
+* Unspec Group 2
 
-    * :ref:`UNSPEC_DEFINE <SphinxRefTarget>`
+* `Unspec Group 3 <unspec-group-3.html>`_
 
-    * `UNSPEC_DEFINE_2 <https://foo>`_
+* :ref:`unspec_func() <SphinxRefUnspecFunc>`
 
-    * :c:type:`unspec_type`
+* :c:func:`func`
 
-    * `unspec_type_2 <https://bar>`_
+* :c:type:`td`
+
+* :c:macro:`DEFINE`
+
+* :ref:`UNSPEC_DEFINE <SphinxRefTarget>`
+
+* `UNSPEC_DEFINE_2 <https://foo>`_
+
+* :c:type:`unspec_type`
+
+* `unspec_type_2 <https://bar>`_
 
 .. Generated from spec:/b
 
@@ -130,21 +135,22 @@ NOTES:
 b
 -
 
-CONSTANT:
-    ``b``
+.. rubric:: CONSTANT:
 
-OPTION TYPE:
-    This configuration option is a boolean feature define.
+``b``
 
-DEFAULT CONFIGURATION:
-    If this configuration option is undefined, then the described feature is not
-    enabled.
+.. rubric:: OPTION TYPE:
 
-DESCRIPTION:
-    description b
+This configuration option is a boolean feature define.
 
-NOTES:
-    None.
+.. rubric:: DEFAULT CONFIGURATION:
+
+If this configuration option is undefined, then the described feature is not
+enabled.
+
+.. rubric:: DESCRIPTION:
+
+description b
 
 .. Generated from spec:/c
 
@@ -155,23 +161,29 @@ NOTES:
 c
 -
 
-CONSTANT:
-    ``c``
+.. rubric:: CONSTANT:
+
+``c``
+
+.. rubric:: OPTION TYPE:
 
-OPTION TYPE:
-    This configuration option is an integer define.
+This configuration option is an integer define.
 
-DEFAULT VALUE:
-    The default value is 13.
+.. rubric:: DEFAULT VALUE:
 
-VALUE CONSTRAINTS:
-    constraint d
+The default value is 13.
 
-DESCRIPTION:
-    description c
+.. rubric:: DESCRIPTION:
 
-NOTES:
-    notes c
+description c
+
+.. rubric:: NOTES:
+
+notes c
+
+.. rubric:: CONSTRAINTS:
+
+constraint d
 
 .. Generated from spec:/e
 
@@ -182,20 +194,21 @@ NOTES:
 e
 -
 
-CONSTANT:
-    ``e``
+.. rubric:: CONSTANT:
+
+``e``
 
-OPTION TYPE:
-    This configuration option is an integer define.
+.. rubric:: OPTION TYPE:
 
-DEFAULT VALUE:
-    The default value is 7.
+This configuration option is an integer define.
 
-DESCRIPTION:
-    description e
+.. rubric:: DEFAULT VALUE:
 
-NOTES:
-    None.
+The default value is 7.
+
+.. rubric:: DESCRIPTION:
+
+description e
 
 .. Generated from spec:/f
 
@@ -206,20 +219,21 @@ NOTES:
 f
 -
 
-CONSTANT:
-    ``f``
+.. rubric:: CONSTANT:
+
+``f``
+
+.. rubric:: OPTION TYPE:
+
+This configuration option is an integer define.
 
-OPTION TYPE:
-    This configuration option is an integer define.
+.. rubric:: DEFAULT VALUE:
 
-DEFAULT VALUE:
-    The default value is 1.
+The default value is 1.
 
-DESCRIPTION:
-    description f
+.. rubric:: DESCRIPTION:
 
-NOTES:
-    None.
+description f
 
 .. Generated from spec:/h
 
@@ -230,20 +244,21 @@ NOTES:
 h
 -
 
-CONSTANT:
-    ``h``
+.. rubric:: CONSTANT:
 
-OPTION TYPE:
-    This configuration option is an integer define.
+``h``
 
-DEFAULT VALUE:
-    The default value is 1.
+.. rubric:: OPTION TYPE:
 
-DESCRIPTION:
-    description h
+This configuration option is an integer define.
 
-NOTES:
-    None.
+.. rubric:: DEFAULT VALUE:
+
+The default value is 1.
+
+.. rubric:: DESCRIPTION:
+
+description h
 
 .. Generated from spec:/i
 
@@ -254,20 +269,21 @@ NOTES:
 i
 -
 
-CONSTANT:
-    ``i``
+.. rubric:: CONSTANT:
+
+``i``
+
+.. rubric:: OPTION TYPE:
 
-OPTION TYPE:
-    This configuration option is an integer define.
+This configuration option is an integer define.
 
-DEFAULT VALUE:
-    The default value is 1.
+.. rubric:: DEFAULT VALUE:
 
-DESCRIPTION:
-    description i
+The default value is 1.
 
-NOTES:
-    None.
+.. rubric:: DESCRIPTION:
+
+description i
 
 .. Generated from spec:/j
 
@@ -278,23 +294,25 @@ NOTES:
 j
 -
 
-CONSTANT:
-    ``j``
+.. rubric:: CONSTANT:
+
+``j``
+
+.. rubric:: OPTION TYPE:
+
+This configuration option is an integer define.
+
+.. rubric:: DEFAULT VALUE:
 
-OPTION TYPE:
-    This configuration option is an integer define.
+Foo bar.
 
-DEFAULT VALUE:
-    Foo bar.
+.. rubric:: DESCRIPTION:
 
-VALUE CONSTRAINTS:
-    constraint d
+description j
 
-DESCRIPTION:
-    description j
+.. rubric:: CONSTRAINTS:
 
-NOTES:
-    None.
+constraint d
 
 .. Generated from spec:/k
 
@@ -305,20 +323,21 @@ NOTES:
 k
 -
 
-CONSTANT:
-    ``k``
+.. rubric:: CONSTANT:
 
-OPTION TYPE:
-    This configuration option is an integer define.
+``k``
 
-DEFAULT VALUE:
-    The default value is 1.
+.. rubric:: OPTION TYPE:
 
-DESCRIPTION:
-    description k
+This configuration option is an integer define.
 
-NOTES:
-    None.
+.. rubric:: DEFAULT VALUE:
+
+The default value is 1.
+
+.. rubric:: DESCRIPTION:
+
+description k
 
 .. Generated from spec:/l
 
@@ -329,28 +348,29 @@ NOTES:
 l
 -
 
-CONSTANT:
-    ``l``
+.. rubric:: CONSTANT:
+
+``l``
+
+.. rubric:: OPTION TYPE:
 
-OPTION TYPE:
-    This configuration option is an initializer define.
+This configuration option is an initializer define.
 
-DEFAULT VALUE:
-    The default value is 1.
+.. rubric:: DEFAULT VALUE:
 
-VALUE CONSTRAINTS:
-    The value of this configuration option shall satisfy all of the following
-    constraints:
+The default value is 1.
 
-    * It shall be greater than or equal to zero.
+.. rubric:: DESCRIPTION:
 
-    * It shall be less than or equal to two.
+description l
 
-DESCRIPTION:
-    description l
+.. rubric:: CONSTRAINTS:
 
-NOTES:
-    None.
+The following constraints apply to this configuration option:
+
+* The value of the configuration option shall be greater than or equal to zero.
+
+* The value of the configuration option shall be less than or equal to two.
 
 .. Generated from spec:/m
 
@@ -361,20 +381,21 @@ NOTES:
 m
 -
 
-CONSTANT:
-    ``m``
+.. rubric:: CONSTANT:
+
+``m``
+
+.. rubric:: OPTION TYPE:
+
+This configuration option is an initializer define.
 
-OPTION TYPE:
-    This configuration option is an initializer define.
+.. rubric:: DEFAULT VALUE:
 
-DEFAULT VALUE:
-    The default value is 1.
+The default value is 1.
 
-DESCRIPTION:
-    description m
+.. rubric:: DESCRIPTION:
 
-NOTES:
-    None.
+description m
 """
         assert content == src.read()
     with open(doxygen_h, "r") as src:
@@ -506,7 +527,7 @@ NOTES:
  * @par Default Value
  * The default value is 13.
  *
- * @par Value Constraints
+ * @par Constraints
  * constraint d
  *
  * @par Notes
@@ -572,7 +593,7 @@ NOTES:
  * @par Default Value
  * Foo bar.
  *
- * @par Value Constraints
+ * @par Constraints
  * constraint d
  */
 #define j
@@ -599,14 +620,14 @@ NOTES:
  * @par Default Value
  * The default value is 1.
  *
- * @par Value Constraints
+ * @par Constraints
  * @parblock
- * The value of this configuration option shall satisfy all of the following
- * constraints:
+ * The following constraints apply to this configuration option:
  *
- * * It shall be greater than or equal to zero.
+ * * The value of the configuration option shall be greater than or equal to
+ *   zero.
  *
- * * It shall be less than or equal to two.
+ * * The value of the configuration option shall be less than or equal to two.
  * @endparblock
  */
 #define l



More information about the vc mailing list