logic)
+ if not example:
+ parent = node.getparent()
+ if parent is not None and etree.QName(parent).localname == "define":
+ grandparent = parent.getparent()
+ if grandparent is not None:
+ # Search grandparent's children
+ for child in grandparent:
+ if not isinstance(child.tag, str):
+ continue
+ child_qname = etree.QName(child)
+
+ if child_qname.namespace == DOCBOOK_NS:
+ if child_qname.localname == "example":
+ screen = child.find("db:screen", namespaces=NAMESPACES)
+ title_node = child.find("db:title", namespaces=NAMESPACES)
+
+ if screen is not None and screen.text:
+ example = screen.text.strip()
+ if title_node is not None:
+ example_title = "".join(title_node.itertext()).strip()
+ break
+
+ elif child_qname.localname == "screen" and child.text:
+ example = child.text.strip()
+ break
+
+ el = RncElement(
+ name=name,
+ pattern_name=current_pattern,
+ description=desc,
+ example=example,
+ example_title=example_title
+ )
+ self.elements.append(el)
+
+ # Check for attributes and children
+ self._analyze_children(node, el)
+
+ elif tag == "ref":
+ name = node.get("name")
+ if name and name not in self.visited_patterns:
+ self.visited_patterns.add(name)
+ if name in self.defines:
+ # Switch to the define node, treating 'name' as current pattern for children
+ self._visit(self.defines[name], current_element, current_pattern=name)
+
+ elif tag == "start":
+ # Document the start element
+ name = "start"
+ # Avoid re-adding start if visited (though start is usually unique)
+ if not any(e.name == "start" for e in self.elements):
+ desc = self._get_doc(node)
+ el = RncElement(name=name, description=desc)
+ self.elements.append(el)
+ self._analyze_children(node, el)
+
+ elif tag == "define":
+ pattern_name = node.get("name")
+ for child in node:
+ self._visit(child, current_element, current_pattern=pattern_name)
+
+ elif tag in ("group", "choice", "interleave", "optional", "zeroOrMore", "oneOrMore"):
+ for child in node:
+ self._visit(child, current_element, current_pattern=current_pattern)
+
+ def _analyze_children(self, element_node: etree._Element, rnc_element: RncElement) -> None:
+ """Analyze the children of an element definition to find attributes, child elements.
+
+ Build the content model string.
+ """
+ # 1. Collect attributes and list of child references (side-effect: populates rnc_element)
+ self._collect_element_content(element_node, rnc_element)
+
+ # 2. Build textual content model (e.g. "(foo | bar)+")
+ model = self._build_content_model_str(element_node, level=0)
+ if model:
+ rnc_element.content_model = model
+
+ # 3. Infer simple data type if applicable
+ rnc_element.data_type = self._get_simple_content_type(element_node)
+
+ def _get_simple_content_type(self, node: etree._Element, visited: set[str] | None = None) -> str | None: # noqa: C901
+ """Check if the node defines a simple data type (data, value, or enum) and return its description.
+
+ Returns None if the content is complex (elements, mixed, etc).
+ """
+ if visited is None:
+ visited = set()
+
+ for child in node:
+ if not isinstance(child.tag, str):
+ continue
+ tag = etree.QName(child).localname
+
+ if tag in ("attribute", "documentation", "refpurpose", "example", "param"):
+ continue
+
+ if tag == "data":
+ return self._get_attribute_type(node) # Reuse logic which handles data/params
+
+ if tag == "choice":
+ # Check if it looks like an enum (choice of values)
+ type_info = self._get_attribute_type(node)
+ if type_info and "Enum" in type_info:
+ return type_info
+ # Otherwise drill down?
+ # If it is Choice of Refs to Data?
+ pass
+
+ if tag == "value":
+ if child.text:
+ return f"Value: {child.text}"
+
+ if tag == "ref":
+ ref_name = child.get("name")
+ if ref_name:
+ if self._is_attribute_def(ref_name):
+ continue
+
+ if self._resolve_ref_to_element(ref_name):
+ # Points to element -> Complex
+ return None
+
+ if ref_name in self.defines and ref_name not in visited:
+ visited.add(ref_name)
+ # We recurse into the definition
+ # Logic: if the definition returns a type, we take it.
+ res = self._get_simple_content_type(self.defines[ref_name], visited)
+ if res:
+ return res
+
+ if tag in ("group", "interleave", "optional", "zeroOrMore", "oneOrMore"):
+ res = self._get_simple_content_type(child, visited)
+ if res:
+ return res
+
+ if tag in ("element", "text", "empty"):
+ return None
+
+ return None
+
+
+ def _dedent(self, text: str) -> str:
+ """Dedent a multiline string by 2 spaces (ignoring first line)."""
+ if "\n" not in text:
+ return text
+ lines = text.split("\n")
+ new_lines = [lines[0]]
+ for line in lines[1:]:
+ if line.startswith(" "):
+ new_lines.append(line[2:])
+ else:
+ new_lines.append(line)
+ return "\n".join(new_lines)
+
+ def _quantify(self, text: str, op: str) -> str:
+ """Apply quantifier, escaping the operator if necessary (e.g. after backticks)."""
+ # If text ends with backticks (inline literal) or a closing delimiter that creates ambiguity,
+ # we must escape the quantifier asterisk/plus/opt to prevent RST parsing errors.
+ # Specifically "Inline literal start-string without end-string".
+ if text.strip().endswith("``"):
+ return f"{text}\\{op}"
+ return f"{text}{op}"
+
+ def _build_content_model_str(self, node: etree._Element, level: int = 0) -> str | None: # noqa: C901
+ """Recursive function to build content model string, ignoring attributes."""
+ tag = etree.QName(node).localname
+
+ indent = " " * level
+ # Indent for children of this node
+ sub_indent = " " * (level + 1)
+ nl = "\n"
+
+ # Check children recursively
+ children_strs = []
+ for child in node:
+ if child.tag is etree.Comment or child.tag is etree.ProcessingInstruction:
+ continue
+ if not isinstance(child.tag, str):
+ continue
+
+ child_tag = etree.QName(child).localname
+
+ if child_tag == "attribute":
+ continue
+ elif child_tag == "element":
+ name = child.get("name")
+ if name:
+ children_strs.append(f"<{name}>")
+ else:
+ # Recursive anonymous element
+ res = self._build_content_model_str(child, level + 1)
+ if res:
+
+ children_strs.append(res)
+ elif child_tag == "ref":
+ ref_name = child.get('name')
+ if ref_name:
+ if self._is_attribute_def(ref_name):
+ continue
+
+ resolved = self._resolve_ref_to_element(ref_name)
+ if resolved:
+ children_strs.append(f"<{resolved}>")
+ else:
+ # If a pattern ref does not resolve to a SINGLE element,
+ # it might be a choice/group of elements (like ds.htmlblock).
+ # We should try to expand it if it's purely content.
+ expanded = self._expand_ref_to_content(ref_name, level)
+ if expanded:
+ children_strs.append(expanded)
+ else:
+ children_strs.append(f"{{{ref_name}}}")
+ elif child_tag == "text":
+ children_strs.append("``text``")
+ elif child_tag == "empty":
+ children_strs.append("``empty``")
+ elif child_tag == "data":
+ children_strs.append(f"data({child.get('type','')})")
+ elif child_tag == "value":
+ children_strs.append(f'"{child.text}"')
+ elif child_tag in ("group", "choice", "interleave", "optional", "zeroOrMore", "oneOrMore"):
+ res = self._build_content_model_str(child, level + 1)
+ if res:
+
+ children_strs.append(res)
+
+ if not children_strs:
+ return None
+
+ # Helper to decide if we need multiline
+ is_complex = len(children_strs) > 1
+
+ # Combine children based on current node type
+ if tag == "optional":
+ # For optional/zeroOrMore/oneOrMore, we wrap the content
+ # If content is single item and simple, standard wrap.
+ # If multiple items (implicitly group?), treat as group?
+ # Usually parent handles group. But if
, it implies group.
+
+ if is_complex:
+ sep = f"{nl}{sub_indent}| " # Logic check: optional with multiple children implies choice usually in DTDs but in RNG it is group unless
used?
+ # RNG spec: content is a pattern. If multiple elements, it's a group.
+ sep = f",{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})?"
+ else:
+ inner = children_strs[0]
+ return self._quantify(self._dedent(inner), "?")
+
+ elif tag == "zeroOrMore":
+ if is_complex:
+ sep = f",{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})*"
+ else:
+ inner = children_strs[0]
+ return self._quantify(self._dedent(inner), "*")
+
+ elif tag == "oneOrMore":
+ if is_complex:
+ sep = f",{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})+"
+ else:
+ inner = children_strs[0]
+ return self._quantify(self._dedent(inner), "+")
+
+ elif tag == "choice":
+ if not is_complex:
+ return self._dedent(children_strs[0])
+ sep = f"{nl}{sub_indent}| "
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})"
+
+ elif tag == "group":
+ if not is_complex:
+ return self._dedent(children_strs[0])
+ sep = f",{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})"
+
+ elif tag == "interleave":
+ if not is_complex:
+ return self._dedent(children_strs[0])
+ sep = f" &{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})"
+
+ # Default (element definition or implicit sequence)
+ if hasattr(node, "__iter__") and is_complex:
+ sep = f",{nl}{sub_indent}"
+ inner = sep.join(children_strs)
+ return f"({nl}{sub_indent}{inner}{nl}{indent})"
+
+ return self._dedent(children_strs[0]) if children_strs else None
+
+ def _collect_element_content(self, node: etree._Element, rnc_element: RncElement, cardinality: str = "1") -> None: # noqa: C901
+ if not hasattr(node, "iter"):
+ return
+
+ for child in node:
+ # Skip comments, processing instructions, etc.
+ if child.tag is etree.Comment or child.tag is etree.ProcessingInstruction:
+ continue
+ if not isinstance(child.tag, str):
+ continue
+
+ tag = etree.QName(child).localname
+
+ if tag == "attribute":
+ attr_name = child.get("name")
+ if attr_name:
+ # check for optional wrapper
+ parent_tag = etree.QName(child.getparent()).localname
+ # Also consider inherited cardinality
+ inherited_optional = cardinality in ("?", "*")
+ is_optional = (parent_tag == "optional") or inherited_optional
+
+ desc = self._get_doc(child)
+ default_val = child.get(f"{{{A_NS}}}defaultValue")
+ type_info = self._get_attribute_type(child)
+
+ rnc_element.attributes.append(RncAttribute(
+ name=attr_name,
+ required=not is_optional,
+ description=desc,
+ default=default_val,
+ type_info=type_info
+ ))
+
+ elif tag == "element":
+ child_name = child.get("name")
+ if child_name:
+ # For choice/optional/oneOrMore, we update cardinality
+ rnc_element.children.append((child_name, cardinality))
+ # Recurse to define this child element globally
+ self._visit(child)
+
+ elif tag == "ref":
+ ref_name = child.get("name")
+ if ref_name:
+ if self._is_attribute_def(ref_name):
+ # If this ref points to attributes, inline them into the current element's attributes
+ if ref_name in self.defines:
+ # Recurse into the definition to extract attributes
+ # Use the same cardinality context
+ self._collect_element_content(self.defines[ref_name], rnc_element, cardinality)
+ else:
+ rnc_element.children.append((f"Ref:{ref_name}", cardinality))
+ if ref_name not in self.visited_patterns:
+ self.visited_patterns.add(ref_name)
+ if ref_name in self.defines:
+ self._visit(self.defines[ref_name])
+
+ elif tag == "optional":
+ # 1 -> ?
+ # + -> *
+ # * -> *
+ # ? -> ?
+ new_card = "*" if cardinality in ("*", "+") else "?"
+ self._collect_element_content(child, rnc_element, new_card)
+
+ elif tag == "zeroOrMore":
+ # Always *
+ self._collect_element_content(child, rnc_element, "*")
+
+ elif tag == "oneOrMore":
+ # 1 -> +
+ # + -> +
+ # * -> *
+ # ? -> * (optional repeated -> *)
+ new_card = "+" if cardinality in ("1", "+") else "*"
+ self._collect_element_content(child, rnc_element, new_card)
+
+ elif tag == "choice":
+ # Choice doesn't change cardinality directly for children unless specific
+ # But in content model it's (A|B).
+ # We just pass through cardinality.
+ self._collect_element_content(child, rnc_element, cardinality)
+
+ elif tag in ("group", "interleave", "define"):
+ self._collect_element_content(child, rnc_element, cardinality)
+
+ def _get_attribute_type(self, node: etree._Element, visited: set[str] | None = None) -> str | None: # noqa: C901
+ """Extract type information (data type, enum values) from an attribute definition."""
+ if visited is None:
+ visited = set()
+
+ # Check for
+ data_node = node.find("rng:data", namespaces=NAMESPACES)
+ if data_node is not None:
+ type_name = data_node.get("type", "string")
+ params = []
+ for param in data_node.findall("rng:param", namespaces=NAMESPACES):
+ p_name = param.get("name")
+ if param.text:
+ params.append(f"{p_name}: {param.text}")
+
+ result = type_name
+ if params:
+ result += f" ({', '.join(params)})"
+ return result
+
+ # Check for (enum)
+ choice_node = node.find("rng:choice", namespaces=NAMESPACES)
+ if choice_node is not None:
+ values = []
+ for val in choice_node.findall("rng:value", namespaces=NAMESPACES):
+ if val.text:
+ values.append(val.text)
+
+ if values:
+ return f"Enum: {', '.join(values)}"
+
+ # Check for [ (reference to type definition)
+ ref_node = node.find("rng:ref", namespaces=NAMESPACES)
+ if ref_node is not None:
+ ref_name = ref_node.get("name")
+ if ref_name and ref_name not in visited:
+ visited.add(ref_name)
+ if ref_name in self.defines:
+ return self._get_attribute_type(self.defines[ref_name], visited)
+
+ return None
+
+
+
+
diff --git a/docs/extensions/rnc2html/tests/test_walker.py b/docs/extensions/rnc2html/tests/test_walker.py
new file mode 100644
index 00000000..66c3c058
--- /dev/null
+++ b/docs/extensions/rnc2html/tests/test_walker.py
@@ -0,0 +1,180 @@
+"""Tests for RNC schema walker logic."""
+from pathlib import Path
+import sys
+
+from lxml import etree # type: ignore[import-untyped]
+
+# Add extension source to path
+# We are in docs/extensions/rnc2html/tests
+EXTENSION_ROOT = Path(__file__).parent.parent / "src"
+sys.path.insert(0, str(EXTENSION_ROOT))
+
+# Import after path setup
+try:
+ from rnc2html.walker import SchemaWalker
+except ImportError as e:
+ # If run standalone, retry assuming relative path issue or module load
+ # But sys.path logic above should fix it
+ print(f"Could not import rnc2html.walker. Check PYTHONPATH setup. Error: {e}")
+ raise e
+
+RNG_SAMPLE = """
+
+
+ ]