Skip to content

Feature: reusing documentation of inherited concepts (groups/fields/symbols) and validate+fix symbols #1650

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

Draft
woutdenolf wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Feature: reusing documentation of inherited concepts (groups/fields/symbols) and validate+fix symbols #1650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c39048
docs: fix collapse summary truncation
woutdenolf Aug 29, 2026
4fbbed1
documentation inheritance would copying
woutdenolf Aug 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
8 changes: 7 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ YCONTRIB_NXDL_TARGETS = $(patsubst %.yaml,%.nxdl.xml,$(subst /nyaml/,/, $(wildca
YAPPDEF_NXDL_TARGETS = $(patsubst %.yaml,%.nxdl.xml,$(subst /nyaml/,/, $(wildcard $(APPDEF_DIR)/nyaml/*.yaml)))


.PHONY: help install style autoformat test clean prepare html pdf impatient-guide all local nxdl nyaml
.PHONY: help install style autoformat test docdiff clean prepare html pdf impatient-guide all local nxdl nyaml

help ::
@echo ""
Expand All @@ -27,6 +27,8 @@ help ::
@echo "make style Check python coding style."
@echo "make autoformat Format all files to the coding style conventions."
@echo "make test Run NXDL syntax and documentation tests."
@echo "make docdiff Diff the generated documentation between two git"
@echo " references. Default: REFS=\"HEAD~1 HEAD\"."
@echo "make clean Remove all build files."
@echo "make prepare (Re)create all build files."
@echo "make html Build HTML version of manual. Requires prepare first."
Expand Down Expand Up @@ -58,6 +60,10 @@ autoformat ::
test ::
$(PYTHON) -m pytest dev_tools

# for example: make docdiff REFS="HEAD~3 ." NXCLASS="-c NXstress"
docdiff ::
$(PYTHON) -m dev_tools docdiff $(NXCLASS) $(REFS)

clean ::
$(RM) -rf $(BUILD_DIR)
$(RM) -rf $(BASE_CLASS_DIR)/$(NYAML_SUBDIR)
Expand Down
15 changes: 15 additions & 0 deletions applications/NXapm.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,21 @@
Number of mass resolution values.
</doc>
</symbol>
<symbol name="n_i">
<doc>Number of pixels along the i direction of a two-dimensional image.</doc>
</symbol>
<symbol name="n_j">
<doc>Number of pixels along the j direction of a two-dimensional image.</doc>
</symbol>
<symbol name="n_x">
<doc>Number of points along the x direction of a three-dimensional grid.</doc>
</symbol>
<symbol name="n_y">
<doc>Number of points along the y direction of a three-dimensional grid.</doc>
</symbol>
<symbol name="n_z">
<doc>Number of points along the z direction of a three-dimensional grid.</doc>
</symbol>
</symbols>
<doc>
Application definition for real or simulated atom probe and field-ion microscopy experiments.
Expand Down
6 changes: 6 additions & 0 deletions applications/NXellipsometry.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,12 @@
Number of angles of incidence of the incident beam.
</doc>
</symbol>
<symbol name="N_observables">
<doc>Number of observables of the measured data (2nd dimension of the measured_data array), as described by 'data_type'.</doc>
</symbol>
<symbol name="N_sensors">
<doc>Number of sensors, one for each varied parameter.</doc>
</symbol>
</symbols>
<doc>
This is the application definition describing ellipsometry experiments.
Expand Down
76 changes: 17 additions & 59 deletions applications/NXstress.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,8 @@
<symbol name="c_Unit">
<doc>Converted diffractogram X units (could be the same as *x_Unit*).</doc>
</symbol>
<symbol name="n_Temp">
<doc>number of temperatures</doc>
</symbol>
<symbol name="n_sField">
<doc>number of values in applied stress field</doc>
</symbol>
<symbol name="n_Temp" reused_from="NXsample"/>
<symbol name="n_sField" reused_from="NXsample"/>
<symbol name="nP">
<doc>number of scan points (only present in scanning measurements)</doc>
</symbol>
Expand All @@ -59,6 +55,20 @@
<doc>number of detector pixels in the second (faster) direction</doc>
</symbol>
</symbols>
<reused_concepts>
<doc>
Concepts that this application definition does not add anything to, but that
are documented here because they are relevant for stress and strain analysis.
</doc>
<reuse path="/ENTRY/title"/>
<reuse path="/ENTRY/experiment_responsible/name"/>
<reuse path="/ENTRY/instrument/DETECTOR/description"/>
<reuse path="/ENTRY/instrument/DETECTOR/dead_time"/>
<reuse path="/ENTRY/instrument/DETECTOR/count_time"/>
<reuse path="/ENTRY/SAMPLE_DESCRIPTION/chemical_formula"/>
<reuse path="/ENTRY/SAMPLE_DESCRIPTION/temperature"/>
<reuse path="/ENTRY/FIT/data_reduction_responsible/name"/>
</reused_concepts>
<doc>
Application definition for stress and strain analysis of crystalline material defined by the `EASI-STRESS consortium &lt;https://easi-stress.eu&gt;`_.

Expand Down Expand Up @@ -106,9 +116,6 @@
<item value="NXstress" />
</enumeration>
</field>
<field name="title" minOccurs="0" maxOccurs="1">
<doc>Extended title for the entry.</doc>
</field>
<field name="experiment_identifier" minOccurs="0" maxOccurs="1">
<doc>
Unique identifier for the experiment as defined by the facility (e.g. DOI, proposal id, ...). At ILL, this could be, for example, ``exp_1-02-286``, ``exp_INDU-229``, or ``exp_INTER-569``.
Expand Down Expand Up @@ -196,10 +203,8 @@
</field>
<group name="experiment_responsible" type="NXuser" minOccurs="0" maxOccurs="1">
<doc>Information about the person who performed the experiment.</doc>
<field name="name" type="NX_CHAR" minOccurs="0" maxOccurs="1">
</field>
<field name="role" type="NX_CHAR" minOccurs="0" maxOccurs="1">
<doc>Role of user responsible for this entry. Suggested roes are, for example, ``local contact``, ``beamline_scientist``, ``post_doc``,…</doc>
<doc>Role of user responsible for this entry. Suggested roles are, for example, ``local contact``, ``beamline_scientist``, ``post_doc``,…</doc>
</field>
</group>
<group name="instrument" type="NXinstrument" minOccurs="1" maxOccurs="1">
Expand Down Expand Up @@ -258,9 +263,6 @@
</group>
<group name="DETECTOR" nameType="any" type="NXdetector" minOccurs="1" maxOccurs="unbounded">
<doc>Zero or more of these groups describe the detectors used in the experiment.</doc>
<field name="description" type="NX_CHAR" minOccurs="0" maxOccurs="1">
<doc>name/manufacturer/model/etc. information</doc>
</field>
<field name="type" type="NX_CHAR">
<doc>
Description of type such as \ :sup:`3`\ He gas cylinder, \ :sup:`3`\ He PSD, scintillator, fission chamber, proportion counter, ion chamber, CCD, pixel, image plate, CMOS, …
Expand Down Expand Up @@ -309,20 +311,6 @@
<dim index="2" value="j" />
</dimensions>
</field>
<field name="dead_time" type="NX_FLOAT" units="NX_TIME" minOccurs="0" maxOccurs="1">
<doc>Detector dead time</doc>
<dimensions rank="3">
<dim index="1" value="nP" />
<dim index="2" value="i" />
<dim index="3" value="j" />
</dimensions>
</field>
<field name="count_time" type="NX_NUMBER" units="NX_TIME" minOccurs="0" maxOccurs="1">
<doc>Elapsed actual counting time</doc>
<dimensions rank="1">
<dim index="1" value="nP" />
</dimensions>
</field>
<field name="depends_on" type="NX_CHAR" minOccurs="0" maxOccurs="1">
<doc>
The axis on which the detector position depends may be stored
Expand Down Expand Up @@ -442,34 +430,6 @@
Descriptive name of sample
</doc>
</field>
<field name="chemical_formula" minOccurs="0" maxOccurs="1">
<doc>
The chemical formula specified using CIF conventions.
Abbreviated version of CIF standard:

* Only recognized element symbols may be used.
* Each element symbol is followed by a 'count' number. A count of '1' may be omitted.
* A space or parenthesis must separate each cluster of (element symbol + count).
* Where a group of elements is enclosed in parentheses, the multiplier for the
group must follow the closing parentheses. That is, all element and group
multipliers are assumed to be printed as subscripted numbers.
* Unless the elements are ordered in a manner that corresponds to their chemical
structure, the order of the elements within any group or moiety depends on
whether or not carbon is present.
* If carbon is present, the order should be:

- C, then H, then the other elements in alphabetical order of their symbol.
- If carbon is not present, the elements are listed purely in alphabetic order of their symbol.

* This is the *Hill* system used by Chemical Abstracts.
</doc>
</field>
<field name="temperature" type="NX_FLOAT" units="NX_TEMPERATURE" minOccurs="0" maxOccurs="1">
<doc>Sample temperature. This could be a scanned variable</doc>
<dimensions rank="anyRank">
<dim index="1" value="n_Temp"/><!-- could be any length -->
</dimensions>
</field>
<field name="stress_field" type="NX_FLOAT" units="NX_ANY" minOccurs="0" maxOccurs="1">
<doc>Applied external stress field</doc>
<dimensions>
Expand Down Expand Up @@ -587,8 +547,6 @@
</field>
<group name="data_reduction_responsible" type="NXuser" minOccurs="0" maxOccurs="1">
<doc>Information about the person who performed the data reduction.</doc>
<field name="name" type="NX_CHAR" minOccurs="0" maxOccurs="1">
</field>
<field name="role" type="NX_CHAR" minOccurs="0" maxOccurs="1">
<doc>Role of user responsible for this entry. Suggested roles are, for example, ``local contact``, ``beamline_scientist``, ``post_doc``,…</doc>
</field>
Expand Down
2 changes: 1 addition & 1 deletion applications/NXtomophase.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@
fluctuations in the beam between frames.
</doc>
<dimensions rank="1">
<dim index="1" value="nDarkFrames + nBrightFrames + nSampleFrame" />
<dim index="1" value="nDarkFrames + nBrightFrames + nSampleFrames" />
<!-- TODO: nPhase? -->
</dimensions>
</field>
Expand Down
6 changes: 6 additions & 0 deletions base_classes/NXbeam.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@
<symbol name="c">
<doc>Number of moments representing beam divergence (x, y, xy, etc.)</doc>
</symbol>
<symbol name="nx">
<doc>Number of delay points in the FROG trace.</doc>
</symbol>
<symbol name="ny">
<doc>Number of frequency points in the FROG trace.</doc>
</symbol>
</symbols>
<doc>
Properties of the neutron or X-ray beam at a given location.
Expand Down
5 changes: 4 additions & 1 deletion base_classes/NXdetector.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,9 @@
<symbol name="j"><doc>number of detector pixels in the second (faster) direction</doc></symbol>
<symbol name="k"><doc>number of detector pixels in the third (if necessary, fastest) direction</doc></symbol>
<symbol name="tof"><doc>number of bins in the time-of-flight histogram</doc></symbol>
<symbol name="m">
<doc>number of entries in the count-rate correction lookup table</doc>
</symbol>
</symbols>

<doc>
Expand Down Expand Up @@ -731,7 +734,7 @@
In cases where the data is of type :ref:`NXlog` this can also be an NXlog.
</doc>
<dimensions rank="1">
<dim index="1" value="np" />
<dim index="1" value="nP" />
</dimensions>
</field>

Expand Down
5 changes: 5 additions & 0 deletions base_classes/NXdetector_group.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXdetector_group"
type="group" extends="NXobject">
<symbols>
<symbol name="i">
<doc>number of detectors and groups of detectors</doc>
</symbol>
</symbols>
<doc>
Logical grouping of detectors. When used, describes a group of detectors.

Expand Down
11 changes: 11 additions & 0 deletions base_classes/NXevent_data.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,17 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXevent_data"
type="group" extends="NXobject">
<symbols>
<symbol name="i">
<doc>number of events</doc>
</symbol>
<symbol name="j">
<doc>number of pulses</doc>
</symbol>
<symbol name="k">
<doc>number of detector ends that are read out for each event</doc>
</symbol>
</symbols>
<doc>
NXevent_data is a special group for storing data from neutron
detectors in event mode. In this mode, the detector electronics
Expand Down
8 changes: 8 additions & 0 deletions base_classes/NXfilter.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,14 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<symbols>
<symbol name="n_comp">
<doc>number of compositions of the filter material</doc>
</symbol>
<symbol name="nsurf">
<doc>number of reflecting surfaces</doc>
</symbol>
</symbols>
<doc>
For band pass beam filters.

Expand Down
3 changes: 3 additions & 0 deletions base_classes/NXoff_geometry.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@
detecting volumes
</doc>
</symbol>
<symbol name="j">
<doc>length of the winding order list, which is the total number of vertices of all faces</doc>
</symbol>
</symbols>

<doc>
Expand Down
5 changes: 5 additions & 0 deletions base_classes/NXorientation.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXorientation"
type="group" extends="NXobject">
<symbols>
<symbol name="numobj">
<doc>number of objects whose orientation is described</doc>
</symbol>
</symbols>
<doc>
legacy class - recommend to use :ref:`NXtransformations` now

Expand Down
5 changes: 5 additions & 0 deletions base_classes/NXpositioner.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<symbols>
<symbol name="n">
<doc>number of positioner values, which is more than one when the positioner is scanned</doc>
</symbol>
</symbols>
<doc>
A generic positioner such as a motor or piezo-electric transducer.
</doc>
Expand Down
5 changes: 5 additions & 0 deletions base_classes/NXsensor.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXsensor"
type="group" extends="NXcomponent">
<symbols>
<symbol name="n">
<doc>number of sensor values, which is more than one when the value is a vector</doc>
</symbol>
</symbols>
<doc>
A sensor used to monitor an external condition

Expand Down
8 changes: 8 additions & 0 deletions base_classes/NXshape.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXshape"
type="group" extends="NXobject">
<symbols>
<symbol name="numobj">
<doc>number of objects whose shape is described</doc>
</symbol>
<symbol name="nshapepar">
<doc>number of parameters describing the shape</doc>
</symbol>
</symbols>
<doc>
legacy class - (used by :ref:`NXgeometry`) - the shape and size of a component.

Expand Down
5 changes: 5 additions & 0 deletions base_classes/NXtranslation.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
name="NXtranslation"
type="group" extends="NXobject">
<symbols>
<symbol name="numobj">
<doc>number of objects whose position is described</doc>
</symbol>
</symbols>
<doc>
legacy class - (used by :ref:`NXgeometry`) - general spatial location of a component.
</doc>
Expand Down
6 changes: 6 additions & 0 deletions contributed_definitions/NXapm_compositionspace_results.nxdl.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@
Total number of ions in the reconstructed dataset.
</doc>
</symbol>
<symbol name="i">
<doc>Number of values along the axis of the respective one-dimensional plot.</doc>
</symbol>
<symbol name="k">
<doc>Number of labels returned by the clustering.</doc>
</symbol>
</symbols>
<doc>
Application definition for results of the CompositionSpace tool used in atom probe.
Expand Down
Loading
Loading