Merge branch 'main' into 879-document-all-anchors

base_classes/NXbeam.nxdl.xml

@@ -142,4 +142,77 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+
+    <field name="depends_on" minOccurs="0" type="NX_CHAR">
+        <doc>
+            The NeXus coordinate system defines the Z axis to be along the nominal beam
+            direction. This is the same as the McStas coordinate system (see :ref:Design-CoordinateSystem).
+            However, the additional transformations needed to represent an altered beam
+            direction can be provided using this depends_on field that contains the path
+            to a NXtransformations group. This could represent redirection of the beam,
+            or a refined beam direction.
+        </doc>
+    </field>
+
+    <group type="NXtransformations" minOccurs="0">
+        <doc>
+            Direction (and location) for the beam. The location of the beam can be given by
+            any point which it passes through as its offset attribute.
+        </doc>
+        <field name="DIRECTION" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER">
+            <doc>
+                Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1]
+                and passes through the origin
+            </doc>
+            <attribute name="transformation_type">
+                <enumeration>
+                    <item value="translation" />
+                </enumeration>
+            </attribute>
+            <attribute name="vector" type="NX_NUMBER">
+                <doc>
+                    Three values that define the direction of beam vector
+                </doc>
+            </attribute>
+            <attribute name="offset" type="NX_NUMBER">
+                <doc>
+                    Three values that define the location of a point through which the beam passes
+                </doc>
+            </attribute>
+            <attribute name="depends_on" type="NX_CHAR">
+                <doc>
+                    Points to the path to a field defining the location on which this
+                    depends or the string "." for origin.
+                </doc>
+            </attribute>
+        </field>
+        <field name="reference_plane" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER">
+            <doc>
+                Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored.
+                This also defines the parallel and perpendicular components of the beam's polarization.
+                If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin
+            </doc>
+            <attribute name="transformation_type">
+                <enumeration>
+                    <item value="translation" />
+                </enumeration>
+            </attribute>
+            <attribute name="vector" type="NX_NUMBER">
+                <doc>
+                    Three values that define the direction of reference plane normal
+                </doc>
+            </attribute>
+            <attribute name="offset" type="NX_NUMBER">
+                <doc>
+                    Not required as beam direction offset locates the plane
+                </doc>
+            </attribute>
+            <attribute name="depends_on" type="NX_CHAR">
+                <doc>
+                    Points to the path to a field defining the location on which this
+                    depends or the string "." for origin.
+                </doc>
+            </attribute>
+        </field>
+    </group>
 </definition>

base_classes/NXbending_magnet.nxdl.xml

@@ -104,7 +104,7 @@
         NXtransformations group. But NeXus allows them to be stored anywhere.
 
         .. todo::
-        Add a definition for the reference point of a bending magnet.
+          Add a definition for the reference point of a bending magnet.
 
     </doc>
   </field>

base_classes/NXpinhole.nxdl.xml

@@ -54,14 +54,14 @@
 	<field name="diameter" type="NX_NUMBER" units="NX_LENGTH">
 		<doc>Size of the circular hole defining the transmitted beam size.</doc>
 	</field>
-<group type="NXtransformations" minOccurs="0">
-    <doc>
-        This is the group recommended for holding the chain of translation
-        and rotation operations necessary to position the component within
-        the instrument. The dependency chain may however traverse similar groups in
-        other component groups.
-    </doc>
-</group>
+    <group type="NXtransformations" minOccurs="0">
+        <doc>
+            This is the group recommended for holding the chain of translation
+            and rotation operations necessary to position the component within
+            the instrument. The dependency chain may however traverse similar groups in
+            other component groups.
+        </doc>
+    </group>
     <attribute name="default">
         <doc>
             .. index:: plotting
@@ -75,9 +75,4 @@
             for a summary of the discussion.
         </doc>
     </attribute>
-    <group type="NXtransformations">
-      <doc>
-        Transformations used by this component to define its position and orientation.
-      </doc>
-    </group>
 </definition>

manual/source/conf.py

@@ -46,8 +46,12 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.todo'
 ]
 
+# Show `.. todo` directives in the output
+# todo_include_todos = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

manual/source/examples/nexusformat/index.rst

@@ -15,4 +15,4 @@ Please refer to the ``NeXpy`` documentation: https://nexpy.github.io/nexpy/.
 Code examples
 =============
 
-* `Write examples for different NeXus classes <https://github.com/nexusformat/exampledata/blob/-/autogenerated_examples/nxdl/python_scripts/h5py/README.md>`_
+* `Write examples for different NeXus classes <https://github.com/nexusformat/exampledata/blob/-/autogenerated_examples/nxdl/python_scripts/nexusformat/README.md>`_

manual/source/nxdl-files.rst

@@ -0,0 +1,31 @@
+======================
+NXDL File Organisation
+======================
+
+NXDL File Name
+##############
+
+In order for the XML machinery to find and link the code in the various files, the name of the file must be composed of the definition name (matching both the spelling and the case) and a ".nxdl.xml" extension. For example, the base class ``NXarbitrary_example`` should be defined by NXDL code within the ``NXarbitrary_example.nxdl.xml`` file. Note also that the definition name is stated twice in application definitions, once in the ``definition`` tag, and again as the value of an ``item`` contained within the ``field`` tag that is named "definition".
+
+.. code-block:: xml
+   :caption: NXarbitrary_example.nxdl.xml
+   
+   <definition name="NXarbitrary_example">
+   
+   <!-- later -->
+   
+      <field name="definition">
+         <doc>Official NeXus NXDL schema to which this file conforms.</doc>
+         <enumeration>
+            <item value="NXarbitrary_example"/>                
+         </enumeration>
+      </field>
+   </definition>
+
+Documentation Images
+####################
+
+Including images (or other related content) in the documentation of NXDL definitions can be very effective for communicating how different parts of the definition interact. To be properly included in the compilation of the NeXus documentation, the extra files must go into a directory having the same name as the definition without the NX prefix.
+For example, if the ``NXarbitrary_example`` base class has a ``pretty_picture.jpg`` image included in its documentation, then the image file should be located by the path (relative to ``NXarbitrary_example.xml``) ``arbitrary_example/pretty_picture.jpg``.
+
+.. image:: img/nxdl-files.png

manual/source/nxdl.rst

@@ -129,3 +129,4 @@ neutron, X-ray, or muon instrument.
 
 	nxdl_desc
 	nxdl-types
+	nxdl-files

utils/nxdl2rst.py

@@ -337,9 +337,9 @@ def analyzeDimensions(ns, parent):
     optional = False
     for subnode in node_list:
         # Dimension index (starts from index 1)
-        index = subnode.get('index')
-        if not index or not index.isdigit():
-            continue
+        index = subnode.get('index', '')
+        if not index.isdigit():
+            raise RuntimeError("A dimension must have an index")
         index = int(index)
         if index == 0:
             # No longer needed: legacy way to specify that the
@@ -358,31 +358,42 @@ def analyzeDimensions(ns, parent):
             ref = subnode.get('ref')
             if ref:
                 return ' (Rank: same as field %s, Dimensions: same as field %s)' % (ref, ref)
-            dim = "."
+            dim = "."  # dimension has no symbol
 
-        # Dimension is optional
-        optional |= subnode.get('required', '').lower() == "false"
+        # Dimension might be optional
+        if subnode.get('required', 'true').lower() == "false":
+            optional = True
+        elif optional:
+            raise RuntimeError("A required dimension cannot come after an optional dimension")
         if optional:
             dim = '[%s]' % dim
 
         dims[index] = dim
 
+    # When the rank is missing, set to the number of dimensions when
+    # there are dimensions specified and none of them are optional.
+    ndims = len(dims)
     rank = node.get('rank', None)
-    if rank is None:
-        if dims:
-            # the rank is variable because of one or more
-            # dimensions are optional
-            rank = len(dims)
-        else:
-            # the rank is variable because no dimensions
-            # were specified
-            rank = "."
-
-    if dims:
+    if rank is None and not optional and ndims:
+        rank = str(ndims)
+
+    # Validate rank and dimensions
+    rank_is_fixed = rank and rank.isdigit()
+    if optional and rank_is_fixed:
+        raise RuntimeError("A fixed rank cannot have optional dimensions")
+    if rank_is_fixed and ndims and int(rank) != ndims:
+        raise RuntimeError("The rank and the number of dimensions do not correspond")
+
+    # Omit rank and/or dimensions when not specified
+    if rank and dims:
         dims = ', '.join(dims)
         return ' (Rank: %s, Dimensions: [%s])' % (rank, dims)
-    else:
+    elif rank:
         return ' (Rank: %s)' % rank
+    elif dims:
+        dims = ', '.join(dims)
+        return ' (Dimensions: [%s])' % dims
+    return ''
 
 
 def hyperlinkTarget(parent_path, name, nxtype):