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