[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