Merge branch 'dimension_as_char' into detector_channel

.github/workflows/ci.yaml

@@ -14,6 +14,11 @@ on:
  type: boolean
  required: true
  default: false
+ upload:
+ description: 'Upload documentation (pdfs in _static/)'
+ type: boolean
+ required: true
+ default: false
 
 defaults:
  run:
@@ -69,32 +74,36 @@ jobs:
  texlive-fonts-recommended
 
  - name: Generate build files
+ env:
+ GH_TOKEN: ${{ (env.python_version == env.python_deploy_version && (github.event.inputs.deploy || github.event.inputs.upload)) && secrets.GITHUB_TOKEN || 'NONE' }}
  run: |
  make prepare
 
- - name: Build Impatient Guid
+ - name: Build Impatient Guide
  run: |
  make impatient-guide
  ls -lAFgh build/impatient-guide/build/html/index.html
- ls -lAFgh build/impatient-guide/build/latex/NXImpatient.pdf
+ mkdir -p build/html
+ mv build/impatient-guide/build/html build/html/impatient
 
  - name: Build User Manual
  run: |
  make pdf
  make html
  ls -lAFgh build/manual/build/html/index.html
- ls -lAFgh build/manual/build/latex/nexus.pdf
+ mkdir -p build/html
+ mv build/manual/build/html/* build/html
 
- - name: Build and Commit the User Manual
+ - name: Deploy both the User Manual and the Impatient Guide
  if: ${{ github.event.inputs.deploy && env.python_version == env.python_deploy_version }}
- uses: sphinx-notes/pages@master
+ uses: JamesIves/github-pages-deploy-action@v4
  with:
- # path to the conf.py directory
- documentation_path: build/manual/source
+ token: ${{ secrets.GITHUB_TOKEN }}
+ folder: build/html
 
- - name: Deploy the User Manual
- if: ${{ github.event.inputs.deploy && env.python_version == env.python_deploy_version }}
- uses: ad-m/github-push-action@master
+ - name: Upload the User Manual and the Impatient Guide
+ if: ${{ github.event.inputs.upload && env.python_version == env.python_deploy_version }}
+ uses: actions/upload-artifact@v3
  with:
- github_token: ${{ secrets.GITHUB_TOKEN }}
- branch: gh-pages
+ name: nexus-definitions-docs
+ path: build/html

.gitignore

@@ -1,5 +1,6 @@
 # Hidden files
 .*
+!.github
 
 # Python byte / compiled / optimized
 *.py[cod]

README.md

@@ -25,6 +25,14 @@ Open the HTML manual in a web brower for visual verification
 
  firefox build/manual/build/html/index.html
 
+### HTML pages with contributor information
+
+To build the html pages that contains contributor information on the sidebar set a github access token to an environment variable called GH_TOKEN.
+
+Note: If set this will increase the build time of the documentation by approximately a factor of 4.
+
+ setenv GH_TOKEN <access token>
+
 ## Repository content
 
 These are the components that define the structure of NeXus data files 

applications/NXcanSAS.nxdl.xml

@@ -1215,7 +1215,7 @@
  <attribute name="T_axes">
  <enumeration>
  <item value="T">
- <doc>the wavelengths field (as a dimension scale) corresponding to this transmission</doc>
+ <doc>the wavelengths field (as axis coordinates) corresponding to this transmission</doc>
  </item>
  </enumeration>
  </attribute>

applications/NXmx.nxdl.xml

@@ -635,7 +635,7 @@
  True when count-rate correction has been applied, false otherwise.
  </doc>
  </field>
- <field name="countrate_correction_lookup_table" type="NX_NUMBER" >
+ <field name="countrate_correction_lookup_table" type="NX_NUMBER" optional="true">
  <doc>
  The countrate_correction_lookup_table defines the LUT used for count-rate
  correction. It maps a measured count :math:`c` to its corrected value
@@ -865,7 +865,15 @@
  </field>
 
  <group name="incident_wavelength_spectrum" type="NXdata"
- minOccurs="0" />
+ minOccurs="0">
+ <doc>
+ This group is intended for use cases that do not fit the
+ :ref:`incident_wavelength &lt;/NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength-field&gt;`
+ and
+ :ref:`incident_wavelength_weights &lt;/NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength_weights-field&gt;`
+ fields above, perhaps for example a 2D spectrometer.
+ </doc>
+ </group>
 
  <field name="flux" type="NX_FLOAT" units="NX_FLUX" minOccurs="0">
  <doc>

base_classes/NXbeam.nxdl.xml

@@ -48,7 +48,10 @@
  especially valuable in storing the results of instrument simulations in which it is useful
  to specify the beam profile, time distribution etc. at each beamline component. Otherwise,
  its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron
- scattering by the sample, e.g., energy transfer, polarizations.
+ scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is
+ considered as a beamline component and this group may be defined as a subgroup directly inside
+ :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an 
+ :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample).
 
  Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case.
  To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred
@@ -265,7 +268,7 @@
  <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).
+ 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,