Skip to content

Add choice element rendering in documentation #1613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PeterC-DLS merged 3 commits into from
Apr 29, 2026
Merged

Add choice element rendering in documentation #1613

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bc401f8
Add choice element rendering in documentation
mretegan Feb 7, 2026
7b2d11e
Preserve XML document order when rendering
mretegan Feb 7, 2026
6cd4705
Merge branch 'nexusformat:main' into docs-choice-support
mretegan Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 128 additions & 75 deletions dev_tools/docs/nxdl.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ def _get_required_or_optional_text(self, node):
:returns: formatted text
"""
tag = node.tag.split("}")[-1]
if tag in ("field", "group"):
if tag in ("field", "group", "choice"):
optional_default = not self._use_application_defaults
optional = node.get("optional", optional_default) in (True, "true", "1", 1)
recommended = node.get("recommended", None) in (True, "true", "1", 1)
Expand Down Expand Up @@ -624,91 +624,144 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
:param indent: to keep track of indentation level
:param parent_path: NX class path of parent nodes
"""
for node in parent.xpath("nx:field", namespaces=ns):
name = node.get("name")
formatted_name = get_rst_formatted_name(node)
index_name = name
dims = self._analyze_dimensions(ns, node)

optional_text = self._get_required_or_optional_text(node)
self._print(f"{indent}{self._hyperlink_target(parent_path, name, 'field')}")
self._print(f"{indent}.. index:: {index_name} (field)\n")
self._print(
f"{indent}{formatted_name}: "
f"{optional_text}"
f"{self._format_type(node)}"
f"{dims}"
f"{self._format_units(node)}"
f" {self.get_first_parent_ref(f'{parent_path}/{name}', 'field')}"
"\n"
)
# Process children in document order to preserve XML ordering.
for node in parent.xpath("nx:field|nx:group|nx:choice|nx:link", namespaces=ns):
Comment thread
PeterC-DLS marked this conversation as resolved.
tag = node.tag.split("}")[-1]
Comment thread
woutdenolf marked this conversation as resolved.

if tag == "field":
name = node.get("name")
formatted_name = get_rst_formatted_name(node)
index_name = name
dims = self._analyze_dimensions(ns, node)

optional_text = self._get_required_or_optional_text(node)
self._print(
f"{indent}{self._hyperlink_target(parent_path, name, 'field')}"
)
self._print(f"{indent}.. index:: {index_name} (field)\n")
self._print(
f"{indent}{formatted_name}: "
f"{optional_text}"
f"{self._format_type(node)}"
f"{dims}"
f"{self._format_units(node)}"
f" {self.get_first_parent_ref(f'{parent_path}/{name}', 'field')}"
"\n"
)

self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
self._print_doc_enum(indent, ns, node)
self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
self._print_doc_enum(indent, ns, node)

for subnode in node.xpath("nx:attribute", namespaces=ns):
optional = self._get_required_or_optional_text(subnode)
self._print_attribute(
ns,
"field",
subnode,
optional,
indent + self._INDENTATION_UNIT,
parent_path + "/" + name,
)

for subnode in node.xpath("nx:attribute", namespaces=ns):
optional = self._get_required_or_optional_text(subnode)
self._print_attribute(
ns,
"field",
subnode,
optional,
indent + self._INDENTATION_UNIT,
parent_path + "/" + name,
elif tag == "group":
name = node.get("name", "")
formatted_name = get_rst_formatted_name(node)
typ = node.get("type", "untyped (this is an error; please report)")

optional_text = self._get_required_or_optional_text(node)
if typ.startswith("NX"):
if name == "":
name = typ.lstrip("NX").upper()
typ = f":ref:`{typ}`"
hTarget = self._hyperlink_target(parent_path, name, "group")
# target = hTarget.replace(".. _", "").replace(":\n", "")
# TODO: https://github.com/nexusformat/definitions/issues/1057
self._print(f"{indent}{hTarget}")
self._print(
f"{indent}{formatted_name}: {optional_text}{typ} "
f"{self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n"
)

for node in parent.xpath("nx:group", namespaces=ns):
name = node.get("name", "")
formatted_name = get_rst_formatted_name(node)
typ = node.get("type", "untyped (this is an error; please report)")

optional_text = self._get_required_or_optional_text(node)
if typ.startswith("NX"):
if name == "":
name = typ.lstrip("NX").upper()
typ = f":ref:`{typ}`"
hTarget = self._hyperlink_target(parent_path, name, "group")
# target = hTarget.replace(".. _", "").replace(":\n", "")
# TODO: https://github.com/nexusformat/definitions/issues/1057
self._print(f"{indent}{hTarget}")
self._print(
f"{indent}{formatted_name}: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n"
)

self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
self._print_doc_enum(indent, ns, node)
self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
self._print_doc_enum(indent, ns, node)

for subnode in node.xpath("nx:attribute", namespaces=ns):
optional = self._get_required_or_optional_text(subnode)
self._print_attribute(
ns,
"group",
subnode,
optional,
indent + self._INDENTATION_UNIT,
parent_path + "/" + name,
)

for subnode in node.xpath("nx:attribute", namespaces=ns):
optional = self._get_required_or_optional_text(subnode)
self._print_attribute(
nodename = "%s/%s" % (name, node.get("type"))
self._print_full_tree(
ns,
"group",
subnode,
optional,
node,
nodename,
indent + self._INDENTATION_UNIT,
parent_path + "/" + name,
)

nodename = "%s/%s" % (name, node.get("type"))
self._print_full_tree(
ns,
node,
nodename,
indent + self._INDENTATION_UNIT,
parent_path + "/" + name,
)
elif tag == "choice":
name = node.get("name", "")
hTarget = self._hyperlink_target(parent_path, name, "choice")
self._print(f"{indent}{hTarget}")
optional_text = self._get_required_or_optional_text(node).strip("() ")
self._print(
f"{indent}**{name}**: ({optional_text}) "
"Only one of the following groups may be present:\n"
)
self._print_doc_enum(indent, ns, node)

for node in parent.xpath("nx:link", namespaces=ns):
name = node.get("name")
formatted_name = get_rst_formatted_name(node)
self._print(f"{indent}{self._hyperlink_target(parent_path, name, 'link')}")
self._print(
f"{indent}{formatted_name}: "
":ref:`link<Design-Links>` "
f"(suggested target: ``{node.get('target')}``)"
"\n"
)
self._print_doc_enum(indent, ns, node)
# Print each group option within the choice.
for subnode in node.xpath("nx:group", namespaces=ns):
subname = subnode.get("name", "")
typ = subnode.get(
"type", "untyped (this is an error; please report)"
)
if typ.startswith("NX"):
if subname == "":
subname = typ.lstrip("NX").upper()
typ_ref = f":ref:`{typ}`"
else:
typ_ref = typ
sub_indent = indent + self._INDENTATION_UNIT
subTarget = self._hyperlink_target(
parent_path + "/" + name, subname, "group"
)
self._print(f"{sub_indent}{subTarget}")
self._print(f"{sub_indent}**{subname}**: {typ_ref}\n")
self._print_doc_enum(sub_indent, ns, subnode)

# Recursively print any content within this group option.
nodename = "%s/%s" % (subname, subnode.get("type"))
self._print_full_tree(
ns,
subnode,
nodename,
sub_indent + self._INDENTATION_UNIT,
parent_path + "/" + name + "/" + subname,
)

elif tag == "link":
name = node.get("name")
formatted_name = get_rst_formatted_name(node)
self._print(
f"{indent}{self._hyperlink_target(parent_path, name, 'link')}"
)
self._print(
f"{indent}{formatted_name}: "
":ref:`link<Design-Links>` "
f"(suggested target: ``{node.get('target')}``)"
"\n"
)
self._print_doc_enum(indent, ns, node)

else:
raise ValueError(f"Unknown node type: {tag}")

def _print(self, *args, end="\n"):
# TODO: change instances of \t to proper indentation
Expand Down
Loading