def _generate_constraint(content: SphinxContent, item: Item,
item_cache: ItemCache) -> None:
constraint = item["appl-config-option-constraint"]
count = len(constraint)
lines = [] # type: List[str]
_resolve_constraint_links(content, constraint, item_cache)
if count == 1:
if "min" in constraint:
_generate_min_max(lines, constraint["min"], "greater")
elif "max" in constraint:
_generate_min_max(lines, constraint["max"], "less")
elif "set" in constraint:
_generate_set(lines, constraint["set"])
elif "custom" in constraint:
if len(constraint["custom"]) == 1:
lines.extend(constraint["custom"][0].strip().split("\n"))
else:
_start_constraint_list(lines)
_generate_item_custom(lines, constraint)
elif count == 2 and "min" in constraint and "max" in constraint:
minimum = constraint["min"]
maximum = constraint["max"]
lines.append("The value of this configuration option shall be "
f"greater than or equal to {minimum}")
lines.append(f"and less than or equal to {maximum}.")
else:
_start_constraint_list(lines)
_generate_item_min(lines, constraint)
_generate_item_max(lines, constraint)
_generate_item_set(lines, constraint)
_generate_item_custom(lines, constraint)
content.add_definition_item("VALUE CONSTRAINTS:", lines)
def _generate_initializer_or_integer(content: SphinxContent, item: Item,
_option_type: str,
item_cache: ItemCache) -> None:
default_value = item["appl-config-option-default-value"]
if not isinstance(default_value, str) or " " not in default_value:
default_value = f"The default value is {default_value}."
content.add_definition_item("DEFAULT VALUE:", default_value)
_generate_constraint(content, item, item_cache)
def test_add_definition_item():
sc = SphinxContent()
sc.add_definition_item("x", ["y", "z"])
assert sc.content == "\nx\n y\n z\n"
sc = SphinxContent()
sc.add_definition_item("a", "\n b\n")
assert sc.content == "\na\n b\n"
def test_license_and_copyrights():
sc = SphinxContent()
with pytest.raises(ValueError):
sc.register_license("x")
sc.register_copyright("Copyright (C) A")
assert "" == sc.content
sc.add_licence_and_copyrights()
assert ".. SPDX-License-Identifier: CC-BY-SA-4.0\n\n.. Copyright (C) A\n\n" == sc.content
def test_add_lines():
sc = SphinxContent()
sc.add_lines("x")
assert sc.content == "x\n"
sc.add_lines("y", 1)
assert sc.content == "x\n y\n"
sc.add_lines(["a", "b"])
assert sc.content == "x\n y\na\nb\n"
def test_add_line():
sc = SphinxContent()
sc.add_line("x")
assert "x\n" == sc.content
sc.add_line("y", 1)
assert "x\n y\n" == sc.content
sc.add_line("")
assert "x\n y\n\n" == sc.content
def test_write(tmpdir):
sc = SphinxContent()
sc.add_line("x")
path = tmpdir + "/y/z"
sc.write(path)
with open(path, "r") as src:
assert "x\n" == src.read()
def test_add_index_entries():
sc = SphinxContent()
sc.add_index_entries(["x", "y"])
assert "\n.. index:: x\n.. index:: y\n" == sc.content
sc.add_index_entries("z")
assert "\n.. index:: x\n.. index:: y\n\n.. index:: z\n" == sc.content
def test_add_blank_line():
sc = SphinxContent()
sc.add_blank_line()
assert "\n" == sc.content
def test_add_header():
sc = SphinxContent()
sc.add_header("x")
assert "x\n=\n" == sc.content
def test_add_label():
sc = SphinxContent()
sc.add_label("x")
assert ".. _x:\n" == sc.content
def _generate_feature(content: SphinxContent, item: Item, option_type: str,
_item_cache: ItemCache) -> None:
content.add_definition_item("DEFAULT CONFIGURATION:",
_OPTION_DEFAULT_CONFIG[option_type](item))
def _generate_content(group: Item, options: ItemMap,
item_cache: ItemCache) -> SphinxContent:
content = SphinxContent()
group.register_license_and_copyrights(content)
content.add_header(group["appl-config-group-name"], level="=")
content.add_blank_line()
content.add_lines(group["appl-config-group-description"])
for item in sorted(options.values(), key=lambda x: x.uid):
name = item["appl-config-option-name"]
item.register_license_and_copyrights(content)
content.add_index_entries([name] + item["appl-config-option-index"])
content.add_blank_line()
content.add_label(name)
content.add_blank_line()
content.add_header(name, level="-")
content.add_definition_item("CONSTANT:", f"``{name}``")
option_type = item["appl-config-option-type"]
content.add_definition_item("OPTION TYPE:", _OPTION_TYPES[option_type])
_OPTION_GENERATORS[option_type](content, item, option_type, item_cache)
content.add_definition_item("DESCRIPTION:",
item["appl-config-option-description"])
_generate_notes(content, item["appl-config-option-notes"])
content.add_licence_and_copyrights()
return content
def _generate_notes(content: SphinxContent, notes: Optional[str]) -> None:
if not notes:
notes = "None."
content.add_definition_item("NOTES:", notes)
def register_license_and_copyrights(self, content: SphinxContent):
""" Registers the license and copyrights of this item. """
content.register_license(self["SPDX-License-Identifier"])
for statement in self["copyrights"]:
content.register_copyright(statement)
def _generate_glossary_content(terms: ItemMap) -> SphinxContent:
content = SphinxContent()
content.add_header("Glossary", level="*")
content.add_blank_line()
content.add_line(".. glossary::")
content.add_line(":sorted:", indent=1)
macro_to_sphinx = MacroToSphinx()
macro_to_sphinx.set_terms(terms)
for item in sorted(terms.values(),
key=lambda x: x["glossary-term"].lower()):
text = macro_to_sphinx.substitute(item["text"].strip())
item.register_license_and_copyrights(content)
content.add_definition_item(item["glossary-term"], text, indent=1)
content.add_licence_and_copyrights()
return content
