Merge branch 'main' into add-countrate-correction-lut

.gitattributes

@@ -0,0 +1 @@
+.bat text eol=crlf

environment.yml → .github/env-workflow.yml

@@ -1,9 +1,12 @@
 name: nexusformat
+
 channels:
   - defaults
   - conda-forge
   - aps-anl-tag
+
 dependencies:
-  - pip
-  - pip:
-    - -r file:requirements.txt
+  - lxml
+  - pyRestTable
+  - Sphinx
+  - six

.github/workflows/publish-sphinx.yml

@@ -0,0 +1,113 @@
+name: Publish Sphinx Docs to GitHub Pages
+
+on:
+  # Triggers the workflow on push events but only for the main branch
+  push:
+    branches:
+      - main
+
+# see: https://sphinx-notes.github.io/pages/
+# see: https://github.com/marketplace/actions/sphinx-to-github-pages
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@master
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+
+    - name: Install build requirements
+      run: |
+        pip install -r requirements.txt
+
+    - name: Diagnostic
+      run: |
+        pip list
+
+    - name: Run the test suite
+      run: |
+        # stops publishing when known problems are found
+        python utils/test_suite.py
+
+    - name: Prepare for out-of-source Sphinx build
+      run: |
+        rm -rf ./build
+        mkdir ./build
+        python ./utils/build_preparation.py . ./build
+
+    - name: Diagnostic
+      run: |
+        ls -lAFGh
+        ls -lAFGh ./build
+
+    - name: Install LaTeX
+      run: |
+        sudo apt-get update -y && \
+        sudo apt-get install -y \
+          latexmk \
+          texlive-latex-recommended \
+          texlive-latex-extra \
+          texlive-fonts-recommended
+
+    - name: Build impatient guide
+      run: |
+        make -C ./build/impatient-guide html latexpdf
+        ls -lAFGh ./build/impatient-guide/_build/latex/*.pdf
+
+        # Copy to documentation source directory
+        cp \
+          ./build/impatient-guide/_build/latex/NXImpatient.pdf \
+          ./build/manual/source/_static/
+
+    - name: Build PDF of manual
+      run: |
+        # expect next make (PDF) to fail (thus exit 0)
+        # since nexus.ind not found first time
+
+        # extra option for "levels nested too deeply" error
+        ( \
+          make latexpdf \
+            LATEXOPTS="--interaction=nonstopmode" \
+            -C build/manual \
+          || exit 0 \
+        )
+
+        # make that missing file
+        makeindex build/manual/build/latex/nexus.idx
+
+        # build the PDF, still a failure will be noted
+        # but we can ignore it without problem
+        ( \
+          make latexpdf \
+            LATEXOPTS="--interaction=nonstopmode" \
+            -C build/manual \
+          || exit 0\
+        )
+
+        # Copy to documentation source directory
+        cp \
+          ./build/manual/build/latex/nexus.pdf \
+          ./build/manual/source/_static/NeXusManual.pdf
+
+    - name: Include other PDFs
+      run: |
+        wget https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf -O ./build/manual/source/_static/NeXusIntern.pdf
+        wget https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf -O ./build/manual/source/_static/NXtranslate.pdf
+
+    - name: Build (html) and Commit
+      uses: sphinx-notes/pages@master
+      with:
+        # path to conf.py directory
+        documentation_path: build/manual/source
+
+    - name: Publish if refs/tags
+      # remove/comment next line to push right away
+      if: startsWith(github.ref, 'refs/tags')
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages

.github/workflows/syntax-checks.yml

@@ -1,14 +1,21 @@
 name: Syntax Checks
 
-on: [push]
+on:
+  # Triggers the workflow on push or pull request events but only for the main branch
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   build-linux:
     name: CI py${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.6', '3.7', '3.8', '3.9']
+        python-version: ['3.7', '3.8', '3.9', '3.10']
       max-parallel: 5
 
     steps:
@@ -22,7 +29,6 @@ jobs:
         auto-update-conda: true
         channel-priority: true
         channels: defaults,conda-forge
-        # environment-file: environment.yml
         mamba-version: "*"
         python-version: ${{ matrix.python-version }}
         use-only-tar-bz2: true  # required for caching
@@ -40,8 +46,7 @@ jobs:
 
     - name: Install dependencies
       run: |
-        $CONDA/bin/conda env update --file environment.yml --name $ENV_NAME
-        # $CONDA/bin/conda install pytest --name $ENV_NAME
+        $CONDA/bin/conda env update --file .github/env-workflow.yml --name $ENV_NAME
         $CONDA/bin/conda list -r --name $ENV_NAME
       env:
         PY_VER: ${{ matrix.python-version }}

.pydevproject

@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <?eclipse-pydev version="1.0"?><pydev_project>
-<pydev_property name="org.python.pydev.PYTHON_PROJECT_INTERPRETER">Default</pydev_property>
-<pydev_property name="org.python.pydev.PYTHON_PROJECT_VERSION">python 2.7</pydev_property>
+
+    <pydev_property name="org.python.pydev.PYTHON_PROJECT_INTERPRETER">Default</pydev_property>
+
+    <pydev_property name="org.python.pydev.PYTHON_PROJECT_VERSION">python 3.7</pydev_property>
+
 </pydev_project>

BUILDING.rst

@@ -1,29 +1,11 @@
-The GNU "make" program and Python are used to build the 
-NeXus documentation.  The default build assembles
-the HTML version.  You have the choice to 
-build the documentation in two places:
+The documentation relies on Sphinx (a Python package) for its organization. The
+GNU ``make`` program and Python are used to build the NeXus documentation.  The
+default build assembles the HTML version.  You have the choice to build the
+documentation in two places:
 
 * in the source tree
 * out of the source tree
 
-.. TODO: documentation how to build PDF version
-
-In-Tree documentation
-=====================
-
-To build the NeXus documentation within the
-source tree, go to the root directory
-(the directory where this README file is located),
-and type::
-
-    make clean
-    make
-
-The HTML documentation is located in this folder::
-
-    ./manual/build/html/
-
-
 Out-of-Tree documentation
 =========================
 
@@ -84,28 +66,17 @@ The HTML documentation is located in this folder::
 
     $(SOURCE_DIR)/build/manual/build/html/
 
+In-Tree documentation
+=====================
 
-Windows
-=======
-
-Windows development needs more instructions.
-Use the *cmd.exe* shell to build the documentation, not 
-the Windows powershell or there will be Python problems.
-
-Python errors
--------------
-
-On Windows, if the following error is output to the console 
-after typing ``make html`` in the ``$(SOURCE_DIR)/manual`` directory:
-
-  'python' is not recognized as an internal or external command,
-  operable program or batch file.
+To build the NeXus documentation within the
+source tree, go to the root directory
+(the directory where this README file is located),
+and type::
 
-it may be necessary to add Python to the ``PATH`` environment 
-variable, such as one of these lines::
+    make clean
+    make
 
-	set PATH=C:\Python27;%PATH%
-	set PATH=D:\Apps\Anaconda;%PATH%
+The HTML documentation is located in this folder::
 
-Try to avoid installing Python on a directory path that has 
-embedded spaces.  Long series of tedious problems with that.
+    ./manual/build/html/

CHANGES.rst

@@ -12,7 +12,14 @@
 Change History
 ##############
 
-:v2021.10:  expected *2021-10*
+:v2022.03:  expected *2022-03*
+
+    * `#955 <https://github.com/nexusformat/definitions/issues/955>`_
+       Documentation built and published from GitHub Actions workflow
+
+    * `#952 <https://github.com/nexusformat/definitions/issues/952>`_
+       - drop support for Python <3.7 when building documentation & testing NXDL files
+       - included PDF file subdirectory changed from `pdf/` to `_static/`
 
     * `#884 <https://github.com/nexusformat/definitions/issues/884>`_
        switch repository default branch from master to main

Makefile

@@ -6,14 +6,12 @@
 # ref: http://www/gnu.org/software/make/manual/make.html
 
 SUBDIRS = manual impatient-guide
+PYTHON = python3
 
 .PHONY: subdirs $(SUBDIRS) builddir all
 
 subdirs: $(SUBDIRS)
 
-#$(SUBDIRS):
-#	$(MAKE) -C $@
-
 manual :: nxdl2rst
 	$(MAKE) html -C $@
 
@@ -38,14 +36,16 @@ impatient-guide ::
 #	$(MAKE) latexpdf -C $(SUBDIRS)
 
 clean:
-	$(MAKE) clean -C $(SUBDIRS)
+	for dir in $(SUBDIRS); do \
+	    $(MAKE) -C $$dir clean; \
+	done
 
 nxdl2rst:
-	$(MAKE) -C manual/source
+	$(MAKE) -C manual/source PYTHON=$(PYTHON)
 
 builddir :: 
 	mkdir -p build
-	python utils/build_preparation.py . build
+	$(PYTHON) utils/build_preparation.py . build
 
 makebuilddir :: builddir
 	$(MAKE) -C build
@@ -62,15 +62,15 @@ rmbuilddir ::
 
 # for developer's use on local build host
 local ::
-	python utils/test_suite.py
+	$(PYTHON) utils/test_suite.py
 	$(RM) -r build
 	mkdir -p build
-	python utils/build_preparation.py . build
+	$(PYTHON) utils/build_preparation.py . build
 	$(MAKE) -C build
 
 # NeXus - Neutron and X-ray Common Data Format
 # 
-# Copyright (C) 2008-2021 NeXus International Advisory Committee (NIAC)
+# Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
 # 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public

README.md

@@ -1,9 +1,10 @@
 * NeXus: https://www.nexusformat.org/
-* citation: [![DOI](https://zenodo.org/badge/19377430.svg)](https://zenodo.org/badge/latestdoi/19377430) (DOI: 10.5281/zenodo.1472392)
-* documentation: https://manual.nexusformat.org/
+* Citation: [![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1472392.svg)](https://doi.org/10.5281/zenodo.1472392)
+* Documentation: https://manual.nexusformat.org/
 * Release Notes: https://github.com/nexusformat/definitions/wiki/Release-Notes
-* build server: http://build.nexusformat.org/
-* travis-ci: syntax check of every NXDL file [![Build Status](https://travis-ci.org/nexusformat/definitions.svg)](https://travis-ci.org/nexusformat/definitions)
+* License: [![License](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+* Continuous Integration: [![Syntax Checking](https://github.com/nexusformat/definitions/actions/workflows/syntax-checks.yml/badge.svg)](https://github.com/nexusformat/definitions/actions/workflows/syntax-checks.yml)
+* Continuous Deployment: [![Publish Documentation](https://github.com/nexusformat/definitions/actions/workflows/publish-sphinx.yml/badge.svg)](https://github.com/nexusformat/definitions/actions/workflows/publish-sphinx.yml)
 
 These are the components that define the structure of NeXus data files 
 in the development directory.

applications/NXarchive.nxdl.xml

@@ -3,7 +3,7 @@
 <!--
 # NeXus - Neutron and X-ray Common Data Format
 # 
-# Copyright (C) 2008-2021 NeXus International Advisory Committee (NIAC)
+# Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
 # 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public

applications/NXarpes.nxdl.xml

@@ -3,7 +3,7 @@
 <!--
 # NeXus - Neutron and X-ray Common Data Format
 # 
-# Copyright (C) 2012-2021 NeXus International Advisory Committee (NIAC)
+# Copyright (C) 2012-2022 NeXus International Advisory Committee (NIAC)
 # 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -80,13 +80,13 @@
         <field name="entrance_slit_setting" type="NX_NUMBER" units="NX_ANY">
           <doc>dial setting of the entrance slit</doc>
         </field>
-        <field name="entrance_slit_size" units="NX_LENGTH">
+        <field name="entrance_slit_size" type="NX_NUMBER" units="NX_LENGTH">
           <doc>size of the entrance slit</doc>
         </field>
-        <field name="pass_energy" units="NX_ENERGY">
+        <field name="pass_energy" type="NX_NUMBER" units="NX_ENERGY">
           <doc>energy of the electrons on the mean path of the analyser</doc>
         </field>
-        <field name="time_per_channel" units="NX_TIME">
+        <field name="time_per_channel" type="NX_NUMBER" units="NX_TIME">
           <doc>todo: define more clearly</doc>
         </field>
         <field name="angles" type="NX_NUMBER" units="NX_ANGLE">

applications/NXcanSAS.nxdl.xml

@@ -3,7 +3,7 @@
 <!--
 # NeXus - Neutron and X-ray Common Data Format
 # 
-# Copyright (C) 2012-2021 NeXus International Advisory Committee (NIAC)
+# Copyright (C) 2012-2022 NeXus International Advisory Committee (NIAC)
 # 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public

applications/NXdirecttof.nxdl.xml

@@ -3,7 +3,7 @@
 <!--
 # NeXus - Neutron and X-ray Common Data Format
 # 
-# Copyright (C) 2008-2021 NeXus International Advisory Committee (NIAC)
+# Copyright (C) 2008-2022 NeXus International Advisory Committee (NIAC)
 # 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public