Reconfigures NeXpy to use Github Actions for documentation

.github/workflows/sphinx.yml

@@ -0,0 +1,31 @@
+name: "Sphinx: Render Documentation"
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'docs'
+  pull_request:
+    branches:
+      - 'docs'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      if: ${{github.ref == 'refs/heads/docs'}}
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

README.rst

@@ -1,8 +1,8 @@
 Installation
 ============
 Released versions of NeXpy are available on `PyPI 
-<https://pypi.python.org/pypi/NeXpy/>`_ and `conda-forge 
-<https://anaconda.org/conda-forge/nexpy>`_. 
+<https://pypi.python.org/pypi/NeXpy/>`__ and `conda-forge 
+<https://anaconda.org/conda-forge/nexpy>`__. 
 
 You can therefore install using 'pip'::
 
@@ -16,25 +16,25 @@ or 'conda'::
           automatically searched when installing. Just type 
           ``conda config --add channels conda-forge``. 
 
-If you have the `Python Setup Tools 
-<https://pypi.python.org/pypi/setuptools>`_, you can install the package 
-from the source code either by downloading one of the `Github releases 
-<https://github.com/nexpy/nexpy/releases>`_ or by cloning the latest 
-development version in the `NeXpy Git repository 
-<https://github.com/nexpy/nexpy>`_::
+If you have the `Python Setup Tools
+<https://pypi.python.org/pypi/setuptools>`__, you can install the
+package from the source code either by downloading one of the `Github
+releases <https://github.com/nexpy/nexpy/releases>`__ or by cloning the
+latest development version in the `NeXpy Git repository
+<https://github.com/nexpy/nexpy>`__::
 
     $ git clone https://github.com/nexpy/nexpy.git
 
-Then use standard Python tools to build and/or install a distribution from
-within the source directory::
+Then use standard Python tools to build and/or install a distribution
+from within the source directory::
 
     $ python -m build  # build a distribution
     $ python -m pip install .  # install the package
 
-The Python API for reading and writing NeXus files is in a separate package, 
-`nexusformat <https://github.com/nexpy/nexusformat>`_, which is also available 
-on `PyPI <https://pypi.python.org/pypi/nexusformat>`_ and `conda-forge
-<https://anaconda.org/conda-forge/nexusformat>`_. 
+The Python API for reading and writing NeXus files is in a separate
+package, `nexusformat <https://github.com/nexpy/nexusformat>`__, which
+is also available on `PyPI <https://pypi.python.org/pypi/nexusformat>`__
+and `conda-forge <https://anaconda.org/conda-forge/nexusformat>`__. 
 
 If the NeXpy GUI is not required, the package may be used in any Python
 shell. It may be installed using:: 
@@ -45,31 +45,32 @@ or::
 
     $ conda install -c conda-forge nexusformat
 
-The package can also be installed from the source code either by downloading 
-one of the `Github releases <https://github.com/nexpy/nexusformat/releases>`_ 
-or by cloning the latest development version in the `NeXpy Git repository 
-<https://github.com/nexpy/nexusformat>`_::
+The package can also be installed from the source code either by
+downloading one of the `Github releases
+<https://github.com/nexpy/nexusformat/releases>`__ or by cloning the
+latest development version in the `NeXpy Git repository
+<https://github.com/nexpy/nexusformat>`__::
 
     $ git clone https://github.com/nexpy/nexusformat.git
 
 Required Libraries
 ==================
 Python Command-Line API
 -----------------------
-NeXpy provides a GUI interface to the 
-`nexusformat API <https://github.com/nexpy/nexusformat>`_, which uses 
-`h5py <http://h5py.org>`_ to read and write HDF5 files that implement the 
-`NeXus data format standard <https://www.nexusformat.org>`_. It does not use 
-the NeXus C API, which means that the current version cannot read and write 
-legacy HDF4 or XML NeXus files. One of the 
-`NeXus conversion utilities <https://manual.nexusformat.org/utilities.html>`_ 
+NeXpy provides a GUI interface to the `nexusformat API
+<https://github.com/nexpy/nexusformat>`__, which uses `h5py
+<http://h5py.org>`__ to read and write HDF5 files that implement the
+`NeXus data format standard <https://www.nexusformat.org>`__. It does
+not use the NeXus C API, which means that the current version cannot
+read and write legacy HDF4 or XML NeXus files. One of the `NeXus
+conversion utilities <https://manual.nexusformat.org/utilities.html>`__
 should be used to convert such files to HDF5.
 
-If you only intend to utilize the Python API from the command-line, the only 
-other required libraries are `NumPy <https://numpy.org>`_ and `SciPy 
-<http://scipy.org>`_. Autocompletion of group and field paths within an
-open file is available if `IPython 
-<https://ipython.org/>`_ is installed.
+If you only intend to utilize the Python API from the command-line, the
+only other required libraries are `NumPy <https://numpy.org>`__ and
+`SciPy <http://scipy.org>`__. Autocompletion of group and field paths
+within an open file is available if `IPython <https://ipython.org/>`__
+is installed.
 
 =================  =================================================
 Library            URL
@@ -83,16 +84,16 @@ IPython            https://ipython.org/
 
 NeXpy GUI
 ---------
-The GUI is built using the PyQt. The 
-`qtpy package <https://github.com/spyder-ide/qtpy>`_ is used to import
-whatever PyQt library is installed, whether PyQt5, PyQt6, PySide2, or PySide6.
+The GUI is built using the PyQt. The `qtpy package
+<https://github.com/spyder-ide/qtpy>`__ is used to import whatever PyQt
+library is installed, whether PyQt5, PyQt6, PySide2, or PySide6.
 
-NeXpy embeds an `IPython shell <http://ipython.org/>`_ and 
-`Matplotlib plotting pane <http://matplotlib.sourceforge.net>`_, within a Qt 
-GUI based on the Jupyter QtConsole with an in-process kernel.
+NeXpy embeds an `IPython shell <http://ipython.org/>`__ and `Matplotlib
+plotting pane <http://matplotlib.sourceforge.net>`__, within a Qt GUI
+based on the Jupyter QtConsole with an in-process kernel.
 
 Least-squares fitting of 1D data uses the `LMFIT package 
-<https://lmfit.github.io/lmfit-py/>`_.
+<https://lmfit.github.io/lmfit-py/>`__.
 
 =================  =================================================
 Library            URL
@@ -110,12 +111,12 @@ mplcursors         https://mplcursors.readthedocs.io/
 Additional Packages
 -------------------
 Importers may require additional libraries to read the imported files in their 
-native format, *e.g.*, `spec2nexus <http://spec2nexus.readthedocs.org/>`_ for 
-reading SPEC files and `FabIO <https://pythonhosted.org/fabio/>`_ for 
+native format, *e.g.*, `spec2nexus <http://spec2nexus.readthedocs.org/>`__ for 
+reading SPEC files and `FabIO <https://pythonhosted.org/fabio/>`__ for 
 importing TIFF and CBF images. 
 
 From v0.9.1, a new 2D smoothing option is available in the list of 
-interpolations in the signal tab if `astropy <http://www.astropy.org>`_
+interpolations in the signal tab if `astropy <http://www.astropy.org>`__
 is installed. It is labelled 'convolve' and provides, by default, a 
 2-pixel Gaussian smoothing of the data. The number of pixels can be 
 changed in the shell by setting ``plotview.smooth``.
@@ -142,26 +143,28 @@ The -r option restores all files loaded in the previous session.
 
 Semantic Versioning
 -------------------
-NeXpy uses `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`_.
+NeXpy uses `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`__.
 
 User Support
 ------------
-Consult the `NeXpy documentation <http://nexpy.github.io/nexpy/>`_ for details 
-of both the Python command-line API and how to use the NeXpy GUI. If you have 
-any general questions concerning the use of NeXpy, please address 
-them to the `NeXus Mailing List 
-<http://download.nexusformat.org/doc/html/mailinglist.html>`_. If you discover
-any bugs, please submit a `Github issue 
-<https://github.com/nexpy/nexpy/issues>`_, preferably with relevant tracebacks.
+Consult the `NeXpy documentation <http://nexpy.github.io/nexpy/>`__ for
+details of both the Python command-line API and how to use the NeXpy
+GUI. If you have any general questions concerning the use of NeXpy,
+please address them to the `NeXus Mailing List
+<http://download.nexusformat.org/doc/html/mailinglist.html>`__. If you
+discover any bugs, please submit a `Github issue
+<https://github.com/nexpy/nexpy/issues>`__, preferably with relevant
+tracebacks.
 
 Acknowledgements
 ----------------
-The `NeXus format <http://www.nexusformat.org>`_ for neutron, x-ray and muon 
-data is developed by an international collaboration under the supervision of the 
-`NeXus International Advisory Committee <https://www.nexusformat.org/NIAC.html>`_. 
-The Python tree API used in NeXpy was originally developed by Paul Kienzle, who
-also wrote the standard Python interface to the NeXus C-API. The original 
-version of NeXpy was initially developed by Boyana Norris, Jason Sarich, and 
-Daniel Lowell, and Ray Osborn using wxPython, and formed the inspiration
-for the current PyQt version. I am grateful to Tom Schoonjans for installing
+The `NeXus format <http://www.nexusformat.org>`__ for neutron, x-ray and
+muon data is developed by an international collaboration under the
+supervision of the `NeXus International Advisory Committee
+<https://www.nexusformat.org/NIAC.html>`__. The Python tree API used in
+NeXpy was originally developed by Paul Kienzle, who also wrote the
+standard Python interface to the NeXus C-API. The original version of
+NeXpy was initially developed by Boyana Norris, Jason Sarich, and Daniel
+Lowell, and Ray Osborn using wxPython, and formed the inspiration for
+the current PyQt version. I am grateful to Tom Schoonjans for installing
 the packages on conda-forge.

docs/.nojekyll

@@ -0,0 +1 @@
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1 @@
+furo==2021.11.16