diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml
new file mode 100644
index 00000000..4d77e132
--- /dev/null
+++ b/.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
diff --git a/README.rst b/README.rst
index e0cde348..a76dbe13 100644
--- a/README.rst
+++ b/README.rst
@@ -1,8 +1,8 @@
Installation
============
Released versions of NeXpy are available on `PyPI
-`_ and `conda-forge
-`_.
+`__ and `conda-forge
+`__.
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
-`_, you can install the package
-from the source code either by downloading one of the `Github releases
-`_ or by cloning the latest
-development version in the `NeXpy Git repository
-`_::
+If you have the `Python Setup Tools
+`__, you can install the
+package from the source code either by downloading one of the `Github
+releases `__ or by cloning the
+latest development version in the `NeXpy Git repository
+`__::
$ 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 `_, which is also available
-on `PyPI `_ and `conda-forge
-`_.
+The Python API for reading and writing NeXus files is in a separate
+package, `nexusformat `__, which
+is also available on `PyPI `__
+and `conda-forge `__.
If the NeXpy GUI is not required, the package may be used in any Python
shell. It may be installed using::
@@ -45,10 +45,11 @@ 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 `_
-or by cloning the latest development version in the `NeXpy Git repository
-`_::
+The package can also be installed from the source code either by
+downloading one of the `Github releases
+`__ or by cloning the
+latest development version in the `NeXpy Git repository
+`__::
$ git clone https://github.com/nexpy/nexusformat.git
@@ -56,20 +57,20 @@ Required Libraries
==================
Python Command-Line API
-----------------------
-NeXpy provides a GUI interface to the
-`nexusformat API `_, which uses
-`h5py `_ to read and write HDF5 files that implement the
-`NeXus data format standard `_. 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 `_
+NeXpy provides a GUI interface to the `nexusformat API
+`__, which uses `h5py
+`__ to read and write HDF5 files that implement the
+`NeXus data format standard `__. 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 `__
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 `_ and `SciPy
-`_. Autocompletion of group and field paths within an
-open file is available if `IPython
-`_ is installed.
+If you only intend to utilize the Python API from the command-line, the
+only other required libraries are `NumPy `__ and
+`SciPy `__. Autocompletion of group and field paths
+within an open file is available if `IPython `__
+is installed.
================= =================================================
Library URL
@@ -83,16 +84,16 @@ IPython https://ipython.org/
NeXpy GUI
---------
-The GUI is built using the PyQt. The
-`qtpy package `_ 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
+`__ is used to import whatever PyQt
+library is installed, whether PyQt5, PyQt6, PySide2, or PySide6.
-NeXpy embeds an `IPython shell `_ and
-`Matplotlib plotting pane `_, within a Qt
-GUI based on the Jupyter QtConsole with an in-process kernel.
+NeXpy embeds an `IPython shell `__ and `Matplotlib
+plotting pane `__, within a Qt GUI
+based on the Jupyter QtConsole with an in-process kernel.
Least-squares fitting of 1D data uses the `LMFIT package
-`_.
+`__.
================= =================================================
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 `_ for
-reading SPEC files and `FabIO `_ for
+native format, *e.g.*, `spec2nexus `__ for
+reading SPEC files and `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 `_
+interpolations in the signal tab if `astropy `__
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 `_.
+NeXpy uses `Semantic Versioning `__.
User Support
------------
-Consult the `NeXpy documentation `_ 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
-`_. If you discover
-any bugs, please submit a `Github issue
-`_, preferably with relevant tracebacks.
+Consult the `NeXpy documentation `__ 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
+`__. If you
+discover any bugs, please submit a `Github issue
+`__, preferably with relevant
+tracebacks.
Acknowledgements
----------------
-The `NeXus format `_ for neutron, x-ray and muon
-data is developed by an international collaboration under the supervision of the
-`NeXus International Advisory Committee `_.
-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 `__ for neutron, x-ray and
+muon data is developed by an international collaboration under the
+supervision of the `NeXus International Advisory Committee
+`__. 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.
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index 878fda11..00000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,156 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-BUILDDIR = ../../nexpy-docs
-PDFBUILDDIR = /tmp
-PDF = ../manual.pdf
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
-help:
- @echo "Please use \`make ' where is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " singlehtml to make a single large HTML file"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " devhelp to make HTML files and a Devhelp project"
- @echo " epub to make an epub"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " latexpdf to make LaTeX files and run them through pdflatex"
- @echo " text to make text files"
- @echo " man to make manual pages"
- @echo " texinfo to make Texinfo files"
- @echo " info to make Texinfo files and run them through makeinfo"
- @echo " gettext to make PO message catalogs"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
-
-clean:
- -rm -rf $(BUILDDIR)/*
-
-html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
- @echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/NeXpy.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/NeXpy.qhc"
-
-devhelp:
- $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
- @echo
- @echo "Build finished."
- @echo "To view the help file:"
- @echo "# mkdir -p $$HOME/.local/share/devhelp/NeXpy"
- @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/NeXpy"
- @echo "# devhelp"
-
-epub:
- $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
- @echo
- @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo
- @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
- @echo "Run \`make' in that directory to run these through (pdf)latex" \
- "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(PDFBUILDDIR)/latex
- @echo "Running LaTeX files through pdflatex..."
- make -C $(PDFBUILDDIR)/latex all-pdf
- cp $(PDFBUILDDIR)/latex/*.pdf $(PDF)
- @echo "pdflatex finished; see $(PDF)"
-
-text:
- $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
- @echo
- @echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
- $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
- @echo
- @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo
- @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
- @echo "Run \`make' in that directory to run these through makeinfo" \
- "(use \`make info' here to do that automatically)."
-
-info:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
- @echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
- $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
- @echo
- @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
- @echo
- @echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
- @echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/docs/.nojekyll b/docs/.nojekyll
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/docs/.nojekyll
@@ -0,0 +1 @@
+
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..d0c3cbf1
--- /dev/null
+++ b/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)
diff --git a/doc/make.bat b/docs/make.bat
similarity index 100%
rename from doc/make.bat
rename to docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..32464913
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+furo==2021.11.16
\ No newline at end of file
diff --git a/doc/source/_static/__ignore__.txt b/docs/source/_static/__ignore__.txt
similarity index 100%
rename from doc/source/_static/__ignore__.txt
rename to docs/source/_static/__ignore__.txt
diff --git a/doc/source/conf.py b/docs/source/conf.py
similarity index 100%
rename from doc/source/conf.py
rename to docs/source/conf.py
diff --git a/doc/source/examples.rst b/docs/source/examples.rst
similarity index 100%
rename from doc/source/examples.rst
rename to docs/source/examples.rst
diff --git a/doc/source/favicon.ico b/docs/source/favicon.ico
similarity index 100%
rename from doc/source/favicon.ico
rename to docs/source/favicon.ico
diff --git a/doc/source/images/axis-limits-bar.png b/docs/source/images/axis-limits-bar.png
similarity index 100%
rename from doc/source/images/axis-limits-bar.png
rename to docs/source/images/axis-limits-bar.png
diff --git a/doc/source/images/customize-panel.png b/docs/source/images/customize-panel.png
similarity index 100%
rename from doc/source/images/customize-panel.png
rename to docs/source/images/customize-panel.png
diff --git a/doc/source/images/limits-panel.png b/docs/source/images/limits-panel.png
similarity index 100%
rename from doc/source/images/limits-panel.png
rename to docs/source/images/limits-panel.png
diff --git a/doc/source/images/nexpy-fits.png b/docs/source/images/nexpy-fits.png
similarity index 100%
rename from doc/source/images/nexpy-fits.png
rename to docs/source/images/nexpy-fits.png
diff --git a/doc/source/images/nexpy-gui.png b/docs/source/images/nexpy-gui.png
similarity index 100%
rename from doc/source/images/nexpy-gui.png
rename to docs/source/images/nexpy-gui.png
diff --git a/doc/source/images/nexpy-logo.png b/docs/source/images/nexpy-logo.png
similarity index 100%
rename from doc/source/images/nexpy-logo.png
rename to docs/source/images/nexpy-logo.png
diff --git a/doc/source/images/options-tab.png b/docs/source/images/options-tab.png
similarity index 100%
rename from doc/source/images/options-tab.png
rename to docs/source/images/options-tab.png
diff --git a/doc/source/images/projection-panel.png b/docs/source/images/projection-panel.png
similarity index 100%
rename from doc/source/images/projection-panel.png
rename to docs/source/images/projection-panel.png
diff --git a/doc/source/images/projection-tab.png b/docs/source/images/projection-tab.png
similarity index 100%
rename from doc/source/images/projection-tab.png
rename to docs/source/images/projection-tab.png
diff --git a/doc/source/images/scan-panel.png b/docs/source/images/scan-panel.png
similarity index 100%
rename from doc/source/images/scan-panel.png
rename to docs/source/images/scan-panel.png
diff --git a/doc/source/images/signal-tab.png b/docs/source/images/signal-tab.png
similarity index 100%
rename from doc/source/images/signal-tab.png
rename to docs/source/images/signal-tab.png
diff --git a/doc/source/images/simple-plot.png b/docs/source/images/simple-plot.png
similarity index 100%
rename from doc/source/images/simple-plot.png
rename to docs/source/images/simple-plot.png
diff --git a/doc/source/images/skewed-axis.png b/docs/source/images/skewed-axis.png
similarity index 100%
rename from doc/source/images/skewed-axis.png
rename to docs/source/images/skewed-axis.png
diff --git a/doc/source/images/x-tab.png b/docs/source/images/x-tab.png
similarity index 100%
rename from doc/source/images/x-tab.png
rename to docs/source/images/x-tab.png
diff --git a/doc/source/images/y-tab.png b/docs/source/images/y-tab.png
similarity index 100%
rename from doc/source/images/y-tab.png
rename to docs/source/images/y-tab.png
diff --git a/doc/source/images/z-tab.png b/docs/source/images/z-tab.png
similarity index 100%
rename from doc/source/images/z-tab.png
rename to docs/source/images/z-tab.png
diff --git a/doc/source/images/z-toolbar.png b/docs/source/images/z-toolbar.png
similarity index 100%
rename from doc/source/images/z-toolbar.png
rename to docs/source/images/z-toolbar.png
diff --git a/doc/source/includeme.rst b/docs/source/includeme.rst
similarity index 100%
rename from doc/source/includeme.rst
rename to docs/source/includeme.rst
diff --git a/doc/source/index.rst b/docs/source/index.rst
similarity index 100%
rename from doc/source/index.rst
rename to docs/source/index.rst
diff --git a/doc/source/pythongui.rst b/docs/source/pythongui.rst
similarity index 100%
rename from doc/source/pythongui.rst
rename to docs/source/pythongui.rst
diff --git a/doc/source/pythonshell.rst b/docs/source/pythonshell.rst
similarity index 100%
rename from doc/source/pythonshell.rst
rename to docs/source/pythonshell.rst
diff --git a/doc/source/readers.rst b/docs/source/readers.rst
similarity index 100%
rename from doc/source/readers.rst
rename to docs/source/readers.rst
diff --git a/doc/source/treeapi.rst b/docs/source/treeapi.rst
similarity index 100%
rename from doc/source/treeapi.rst
rename to docs/source/treeapi.rst