From 8c2e71420cb5798ec4bb980d932174afa9b7f62a Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Sun, 29 Sep 2024 06:29:18 -0500 Subject: [PATCH 01/10] ENH #1436 add partial as third choice to nameType --- nxdl.xsd | 1 + 1 file changed, 1 insertion(+) diff --git a/nxdl.xsd b/nxdl.xsd index 1f88a8ccb4..d99d80a93b 100755 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -925,6 +925,7 @@ + From 0b4713bc1fc4057ef35491bc5152537c5a3d5a37 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Sun, 29 Sep 2024 08:33:40 -0500 Subject: [PATCH 02/10] MNT #1436 generalize nameType to fields, groups, and attributes --- nxdl.xsd | 48 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/nxdl.xsd b/nxdl.xsd index d99d80a93b..8291711f98 100755 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -1,5 +1,8 @@ + + + + + + + This interprets the ``name`` attribute as: + + * ``"specified"`` = Exactly this name. + * ``"any"`` = Any name not already used in group. + * ``"partial"`` = The capital letters are substitutable + (empty string allowed) and the lower case letters + (and other allowed symbols, such as ``_``) are not. + + In each case, all names in a NeXus data file must + follow the naming :ref:`rules<Design-Naming>`. + + + + + + + + + + + + @@ -486,6 +515,7 @@ + @@ -913,22 +943,7 @@ - - - - This interprets the name attribute as: - * ``specified`` = use as specified - * ``any`` = can be any name not already used in group - - - - - - - - - - + @@ -1007,6 +1022,7 @@ + From 1dc5522ce8f97caec5c74dad3c888455e1e1cc55 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Sun, 29 Sep 2024 08:35:04 -0500 Subject: [PATCH 03/10] GIT #1436 ignore local XMLSchema.xsd --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 353bdd61c2..1e25594542 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,7 @@ nyaml/ # Unknown /python/ -__github_creds__.txt \ No newline at end of file +__github_creds__.txt + +# used locally to validate nxdl.xsd and nxdlTypes.xsd +XMLSchema.xsd From cf6123277eace8aaa23dd13deac40f469d187c25 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Sun, 29 Sep 2024 08:44:30 -0500 Subject: [PATCH 04/10] DOC #1436 --- CHANGES.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index f9da117b63..7527dadcc3 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -21,6 +21,18 @@ Highlights of each release are described below. For more details, see our wiki (https://github.com/nexusformat/definitions/wiki/Release-Notes) which provides links to the Release Notes (itemized list of changes) for any release. +.. incoming change for next release + + v2025.mm + ++++++++ + + for release sometime in *2025* + + Maintenance + ----------- + + * Add nameType="partial" to NXDL schema. + * Use 'nameType' attribute in fields, groups, and attributes. v2024.02 ++++++++ From 1343b9986dcf52351396104c2a935a2068419829 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 30 Sep 2024 04:33:06 -0500 Subject: [PATCH 05/10] MNT #1436 update nameType in two NXDL files --- applications/NXcanSAS.nxdl.xml | 6 +++--- base_classes/NXdata.nxdl.xml | 13 ++++--------- 2 files changed, 7 insertions(+), 12 deletions(-) diff --git a/applications/NXcanSAS.nxdl.xml b/applications/NXcanSAS.nxdl.xml index c34da29078..6c255e8194 100644 --- a/applications/NXcanSAS.nxdl.xml +++ b/applications/NXcanSAS.nxdl.xml @@ -278,7 +278,7 @@ - + .. index:: NXcanSAS (applications); Q @@ -425,7 +425,7 @@ - + .. index:: NXcanSAS (applications); I @@ -1187,7 +1187,7 @@ ============================ --> - + The *SAStransmission_spectrum* element diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index 9562baa93f..41d3e59355 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -309,12 +309,7 @@ - - - + The ``AXISNAME_indices`` attribute is a single integer or an array of integers that defines which :ref:`data </NXdata/DATA-field>` dimension(s) are spanned by the corresponding axis. The first dimension index is ``0`` (zero). @@ -420,7 +415,7 @@ data label - + "Errors" (meaning *uncertainties* or *standard deviations*) associated with any field named ``FIELDNAME`` in this ``NXdata`` @@ -446,7 +441,7 @@ - + An optional scaling factor to apply to the values in any field named ``FIELDNAME`` in this ``NXdata`` group. This can be a :ref:`DATA </NXdata/DATA-field>` field @@ -468,7 +463,7 @@ When omitted, the scaling factor is assumed to be 1. - + An optional offset to apply to the values in FIELDNAME (usually the signal). From 47bb1e059cf840b6a12bfd7c99d0f5f993e13919 Mon Sep 17 00:00:00 2001 From: woutdenolf Date: Tue, 1 Oct 2024 23:23:00 +0200 Subject: [PATCH 06/10] RST formatting of field, group, attribute and link names to highlight substitutible characters --- dev_tools/docs/nxdl.py | 13 +++++--- dev_tools/utils/nxdl_utils.py | 57 +++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 4 deletions(-) diff --git a/dev_tools/docs/nxdl.py b/dev_tools/docs/nxdl.py index 8c9d548be2..15d50948ab 100644 --- a/dev_tools/docs/nxdl.py +++ b/dev_tools/docs/nxdl.py @@ -14,6 +14,7 @@ from ..globals.urls import REPO_URL from ..utils.github import get_file_contributors_via_api from ..utils.nxdl_utils import get_inherited_nodes +from ..utils.nxdl_utils import get_rst_formatted_name from ..utils.types import PathLike from .anchor_list import AnchorRegistry @@ -564,13 +565,14 @@ def _print_doc_enum(self, indent, ns, node, required=False): def _print_attribute(self, ns, kind, node, optional, indent, parent_path): name = node.get("name") + formatted_name = get_rst_formatted_name(node) index_name = name self._print( f"{indent}" f"{self._hyperlink_target(parent_path, name, 'attribute')}" ) self._print(f"{indent}.. index:: {index_name} ({kind} attribute)\n") self._print( - f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n" + f"{indent}{formatted_name}: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n" ) self._print_doc_enum(indent, ns, node) @@ -592,6 +594,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): """ 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) @@ -599,7 +602,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): self._print(f"{indent}{self._hyperlink_target(parent_path, name, 'field')}") self._print(f"{indent}.. index:: {index_name} (field)\n") self._print( - f"{indent}**{name}**: " + f"{indent}{formatted_name}: " f"{optional_text}" f"{self._format_type(node)}" f"{dims}" @@ -624,6 +627,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): 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) @@ -636,7 +640,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): # TODO: https://github.com/nexusformat/definitions/issues/1057 self._print(f"{indent}{hTarget}") self._print( - f"{indent}**{name}**: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n" + 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) @@ -664,9 +668,10 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): 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}**{name}**: " + f"{indent}{formatted_name}: " ":ref:`link` " f"(suggested target: ``{node.get('target')}``)" "\n" diff --git a/dev_tools/utils/nxdl_utils.py b/dev_tools/utils/nxdl_utils.py index ebb7ce62a3..52821c23e2 100644 --- a/dev_tools/utils/nxdl_utils.py +++ b/dev_tools/utils/nxdl_utils.py @@ -3,6 +3,7 @@ """ import os +import re import textwrap from functools import lru_cache from glob import glob @@ -839,3 +840,59 @@ def get_node_at_nxdl_path( "Please check this entry in the template dictionary." ) return elem + + +def get_rst_formatted_name(node): + """Return the RST formatted name of the node (field, group, link or attribute). + + The formatting is determined as follows: + + - all characters are bold formatted + - substitutable characters are bold and italic formatted + - attributes start with a bold "@" character + """ + name = node.get("name", "") + nameType = node.get("nameType", "") + + node_type = get_local_name_from_xml(node) + + if not name and node_type == "group": + # Derive the name from the type without the NX prefix + group_type = node.get("type", "") + name = group_type.lstrip("NX").upper() + if not nameType: + nameType = "any" + + # Characters that are NOT substitutable + fixstart = "**" + fixstop = "**" + + # Characters that are substitutable + varstart = "*" # TODO: should be bolditalic instead of italic + varstop = "*" + + if nameType == "any": + # Formatting: bold and italicized + if node_type == "attribute": + return fr"{fixstart}@{fixstop}\ {varstart}{name}{varstop}" + else: + return f"{varstart}{name}{varstop}" + + if nameType == "partial": + # Formatting: bold and capital letters italicized + substrings = _SPLIT_NAMETYPE_PARTIAL.findall(name) + formatted_parts = [ + f"{varstart}{s}{varstop}" if s.isupper() else f"{fixstart}{s}{fixstop}" for s in substrings + ] + if node_type == "attribute": + formatted_parts.insert(0, f"{fixstart}@{fixstop}") + return r"\ ".join(formatted_parts) + + # Formatting: bold only + if node_type == "attribute": + return f"{fixstart}@{name}{fixstop}" + else: + return f"{fixstart}{name}{fixstop}" + + +_SPLIT_NAMETYPE_PARTIAL = re.compile(r"[A-Z]+|[^A-Z]+") From f301a2af86d181fe67765605bcc57332b4d102cf Mon Sep 17 00:00:00 2001 From: woutdenolf Date: Tue, 1 Oct 2024 23:30:43 +0200 Subject: [PATCH 07/10] black --- dev_tools/utils/nxdl_utils.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/dev_tools/utils/nxdl_utils.py b/dev_tools/utils/nxdl_utils.py index 52821c23e2..70980c95c1 100644 --- a/dev_tools/utils/nxdl_utils.py +++ b/dev_tools/utils/nxdl_utils.py @@ -868,13 +868,13 @@ def get_rst_formatted_name(node): fixstop = "**" # Characters that are substitutable - varstart = "*" # TODO: should be bolditalic instead of italic + varstart = "*" # TODO: should be bolditalic instead of italic varstop = "*" if nameType == "any": # Formatting: bold and italicized if node_type == "attribute": - return fr"{fixstart}@{fixstop}\ {varstart}{name}{varstop}" + return rf"{fixstart}@{fixstop}\ {varstart}{name}{varstop}" else: return f"{varstart}{name}{varstop}" @@ -882,7 +882,8 @@ def get_rst_formatted_name(node): # Formatting: bold and capital letters italicized substrings = _SPLIT_NAMETYPE_PARTIAL.findall(name) formatted_parts = [ - f"{varstart}{s}{varstop}" if s.isupper() else f"{fixstart}{s}{fixstop}" for s in substrings + f"{varstart}{s}{varstop}" if s.isupper() else f"{fixstart}{s}{fixstop}" + for s in substrings ] if node_type == "attribute": formatted_parts.insert(0, f"{fixstart}@{fixstop}") From 49694a79a28bc91aa0c660ac51070556161e97c7 Mon Sep 17 00:00:00 2001 From: woutdenolf Date: Wed, 2 Oct 2024 18:05:00 +0200 Subject: [PATCH 08/10] add bolditalic inline formatting --- dev_tools/utils/nxdl_utils.py | 4 ++-- manual/source/conf.py | 10 +++++++++- requirements.txt | 1 + 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/dev_tools/utils/nxdl_utils.py b/dev_tools/utils/nxdl_utils.py index 70980c95c1..50e033c681 100644 --- a/dev_tools/utils/nxdl_utils.py +++ b/dev_tools/utils/nxdl_utils.py @@ -868,8 +868,8 @@ def get_rst_formatted_name(node): fixstop = "**" # Characters that are substitutable - varstart = "*" # TODO: should be bolditalic instead of italic - varstop = "*" + varstart = ":bolditalic:`" + varstop = "`" if nameType == "any": # Formatting: bold and italicized diff --git a/manual/source/conf.py b/manual/source/conf.py index 9b90263f10..ed42d19d23 100644 --- a/manual/source/conf.py +++ b/manual/source/conf.py @@ -48,7 +48,8 @@ 'sphinx.ext.githubpages', 'sphinx.ext.todo', 'sphinx_tabs.tabs', - 'contrib_ext' + 'contrib_ext', + 'chios.bolditalic' ] # Show `.. todo` directives in the output @@ -100,6 +101,13 @@ def setup(app): # Output file base name for HTML help builder. htmlhelp_basename = 'NeXusManualdoc' +html_contexthtml_context = { + 'css_files': [ + '_static/bespoke.css', # custom CSS styling + '_static/bolditalic.css', # bolditalic styling + ], + } + # -- Options for Latex output ------------------------------------------------- latex_elements = { 'maxlistdepth':25, # some application definitions are deeply nested diff --git a/requirements.txt b/requirements.txt index ba1f751d3f..4b6ab51d58 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ nyaml sphinx>=5 sphinx-tabs sphinx-toolbox +chios # Testing pytest From f9ceb0b90bb5cc567e5e13de6e5ee23e3e249553 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 14 Oct 2024 08:44:49 -0500 Subject: [PATCH 09/10] DOC #1436 per review --- nxdl.xsd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/nxdl.xsd b/nxdl.xsd index 8291711f98..d51134ac72 100755 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -179,6 +179,8 @@ https://stackoverflow.com/a/48980995/1046449 --> This interprets the ``name`` attribute as: * ``"specified"`` = Exactly this name. + Note that if no ``name`` and ``nameType`` are provided + for a group, ``nameType="any"`` becomes the default. * ``"any"`` = Any name not already used in group. * ``"partial"`` = The capital letters are substitutable (empty string allowed) and the lower case letters From 41d8157e740610355071c2d0c6a59900a1fb475f Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 14 Oct 2024 09:57:17 -0500 Subject: [PATCH 10/10] DOC #1485 add footnote citation --- manual/source/datarules.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/source/datarules.rst b/manual/source/datarules.rst index 2dd703d962..7f7e36b6d3 100644 --- a/manual/source/datarules.rst +++ b/manual/source/datarules.rst @@ -67,8 +67,8 @@ described by the following :index:`rules `: .. rubric:: Regular expression pattern for NXDL group and field names The NIAC recognises that the majority of the world uses characters - outside of the basic latin (a.k.a. US-ASCII, 7-bit ASCII) set - currently included in the allowed names. The restriction given here + outside of the basic latin (a.k.a. US-ASCII, 7-bit ASCII) [#7bit-ASCII]_ + set currently included in the allowed names. The restriction given here reflects current technical issues and we expect to revisit the issue and relax such restrictions in future.