From 206f12de6caa69eb2ec3293eb8f89c85e4719bf7 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 10:41:45 +0100 Subject: [PATCH 01/20] Add doc build workflow --- .github/workflows/docs.yml | 115 +++++++++++++++++++++++++++++++++++++ .readthedocs.yaml | 27 +++++++++ setup.py | 6 +- 3 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 .readthedocs.yaml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..97c48edd0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,115 @@ +name: Docs + +on: [push, pull_request] + +jobs: + build_doc_PR: + # This build is to automatically add comments on PR + name: PR comments + runs-on: ubuntu-latest + env: + BUILD_DEPS: python3-dev build-essential graphviz + LATEX_DEPS: dvipng latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended + + steps: + - uses: actions/checkout@v4 + + - uses: ericpre/sphinx-action@latest_sphinx + with: + pre-build-command: "apt-get update -y && apt-get install -y ${{ env.BUILD_DEPS }} ${{ env.LATEX_DEPS }} && pip install .'[doc]'" + build-command: make html + docs-folder: doc/ + + - uses: actions/upload-artifact@v3 + with: + path: ./doc/_build/html/ + name: docs_build + + build_docs: + # This build is to check links and update table of supported formats + name: Check links + runs-on: ubuntu-latest + env: + DOCS_PATH: ./doc/_build/html/ + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v4 + name: Install Python + with: + python-version: '3.11' + + - name: Install build docs + shell: bash -l {0} + run: | + pip install .'[doc]' + + - name: Check links + shell: bash -l {0} + run: | + cd doc + make linkcheck + + - name: Build docs + shell: bash -l {0} + run: | + cd doc + make SPHINXOPTS="-W --keep-going" html + + - uses: actions/upload-artifact@v3 + with: + path: ${{ env.DOCS_PATH }} + name: docs_html + + push_docs: + # This build is to push changes to gh-pages branch (https://hyperspy.org/exspy) + needs: build_docs + name: Push to gh-pages + runs-on: ubuntu-latest + if: ${{ github.event_name != 'pull_request' && github.repository == 'hyperspy/exspy' }} + permissions: + # needs write permission to push the docs to gh-pages + contents: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: gh-pages + + - uses: actions/download-artifact@v3 + with: + name: docs_html + path: . + + - name: list files + run: | + ls + + - name: Git status + run: | + git status + git status -s + if [[ $(git status -s) ]]; then + HAS_CHANGES='true' + else + HAS_CHANGES='false' + fi + echo "HAS_CHANGES=${HAS_CHANGES}" >> $GITHUB_ENV + + - name: Commit files + # Skip when there is nothing to commit + if: ${{ env.HAS_CHANGES == 'true' }} + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + git add -A + git commit -m "Update docs build" -a + + - name: Push changes + if: ${{ env.HAS_CHANGES == 'true' }} + uses: ad-m/github-push-action@d91a481090679876dfc4178fef17f286781251df + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + branch: gh-pages diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..015d38882 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,27 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: doc/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +formats: + - htmlzip + +python: + install: + - method: pip + path: . + extra_requirements: + - doc diff --git a/setup.py b/setup.py index c01b4b373..c0c6797d7 100644 --- a/setup.py +++ b/setup.py @@ -27,10 +27,10 @@ extra_feature_requirements = { "gui-jupyter": [ - "hyperspy_gui_ipywidgets @ git+https://github.com/ericpre/hyperspy_gui_ipywidgets.git@hyperspy2.0", + "hyperspy_gui_ipywidgets @ https://github.com/hyperspy/hyperspy_gui_ipywidgets/archive/hyperspy2.0.zip", ], "gui-traitsui": [ - "hyperspy_gui_traitsui @ git+https://github.com/ericpre/hyperspy_gui_traitsui.git@hyperspy2.0", + "hyperspy_gui_traitsui @ https://github.com/hyperspy/hyperspy_gui_traitsui/archive/hyperspy2.0.zip", ], "doc": [ "numpydoc", @@ -82,7 +82,7 @@ extras_require=extra_feature_requirements, install_requires=[ "dask[array]", - "hyperspy @ git+https://github.com/hyperspy/hyperspy@RELEASE_next_major", + "hyperspy @ https://github.com/hyperspy/hyperspy/archive/RELEASE_next_major.zip", "matplotlib", "numexpr", "numpy", From 35f022ba1d81a5158ee32277a0ca21369bc42914 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:07:28 +0100 Subject: [PATCH 02/20] Fix links documentation --- doc/citing.rst | 2 +- doc/conf.py | 5 +++++ doc/intro.rst | 4 ++-- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/citing.rst b/doc/citing.rst index 95a22b02f..abb8985c7 100644 --- a/doc/citing.rst +++ b/doc/citing.rst @@ -6,7 +6,7 @@ Citing exSpy If exSpy has been significant to a project that leads to an academic publication, please acknowledge that fact by citing it. The DOI in the -badge below is the `Concept DOI `_ -- +badge below is the `Concept DOI `_ -- it can be used to cite the project without referring to a specific version. If you are citing HoloSpy because you have used it to process data, please use the DOI of the specific version that you have employed. You can diff --git a/doc/conf.py b/doc/conf.py index 6305cbfc1..9fc91b443 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -42,6 +42,11 @@ "sphinx.ext.napoleon", ] +linkcheck_ignore = [ + "https://doi.org/10.1021/acs.nanolett.5b00449", # 403 Client Error: Forbidden for url + "https://onlinelibrary.wiley.com/doi/10.1111/j.1365-2818.2006.01549.x", # 403 Client Error: Forbidden for url +] + intersphinx_mapping = { "dask": ("https://docs.dask.org/en/latest", None), "hyperspy": ("https://hyperspy.org/hyperspy-doc/dev", None), diff --git a/doc/intro.rst b/doc/intro.rst index 9e7a89173..0132201f3 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -73,11 +73,11 @@ Learning resources There are many ways you can help! Citing exSpy -================= +============ If exSpy has been significant to a project that leads to an academic publication, please acknowledge that fact by citing it. The DOI in the -badge below is the `Concept DOI `_ of +badge below is the `Concept DOI `_ of HyperSpy. It can be used to cite the project without referring to a specific version. If you are citing exSpy because you have used it to process data, please use the DOI of the specific version that you have employed. You can From 3a5ec4200561d22250909c492c9bbd2911760002 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:07:39 +0100 Subject: [PATCH 03/20] Add .gitignore --- .gitignore | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..4f21eef4b --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +doc/_build/* +doc/auto_examples/* +build/* +dist/* +*egg-info* \ No newline at end of file From f884adf745cefc2af0b1fe121d66493fa7722de0 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:09:24 +0100 Subject: [PATCH 04/20] Add releasing guide --- releasing_guide.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 releasing_guide.md diff --git a/releasing_guide.md b/releasing_guide.md new file mode 100644 index 000000000..e49f0b764 --- /dev/null +++ b/releasing_guide.md @@ -0,0 +1,35 @@ +# Releasing a new exSpy version + +To publish a new exSpy release do the following steps: + +## Preparation + +- Create a new PR to the 'main' branch for the release process, e.g. `release_v0.1.1` +- Make sure to have the code ready, including changelog +- Set the correct version number in `exSpy/release_info.py` (increase the third + digit for a patch release, the second digit for a regular minor release, the + first digit for a major release) +- Let that PR collect comments for a day to ensure that other maintainers are comfortable + with releasing +- Set correct date and version number in `CHANGES.rst` + +## Tag and Release + +- Create a tag e.g. `git tag -a v0.1.1 -m "exSpy version 0.1.1"` +- Push tag to user fork for a test run `git push origin v0.1.1`. Will run the release + workflow without uploading to PyPi +- Push tag to HoloSpy repository to trigger release `git push upstream v0.1.1` + (this triggers the GitHub action to create the sdist and wheel and upload to + PyPi automatically). :warning: this is a point of no return :warning: + +## Post-release action + +- Increment the version and set it back to dev: `vx.y.zdev0` +- Update version in other branches if necessary +- Prepare `CHANGES.rst` for development by adding `UNRELEASED` headline +- Merge the PR + +## Follow-up + +- Tidy up and close corresponding milestone or project +- A PR to the conda-forge feedstock will be created by the conda-forge bot From 49ed7db1aec82512082034c7587a48a8e6deca27 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:13:58 +0100 Subject: [PATCH 05/20] Fix warning with latest version of `pydata_sphinx_theme` --- doc/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/conf.py b/doc/conf.py index 9fc91b443..e282d8f24 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -92,6 +92,7 @@ "text": "exSpy", }, "header_links_before_dropdown": 6, + "navigation_with_keys": False, } # The name of an image file (relative to this directory) to place at the top From 23ea7b00e548316bcbbac60cbedb9ae6d09ff48d Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:27:52 +0100 Subject: [PATCH 06/20] Fix build doc examples --- doc/conf.py | 21 ++++++++++++++++++-- examples/README.rst | 6 ++++++ examples/model_fitting/EELS_curve_fitting.py | 2 +- setup.py | 1 + 4 files changed, 27 insertions(+), 3 deletions(-) create mode 100644 examples/README.rst diff --git a/doc/conf.py b/doc/conf.py index e282d8f24..1c014eb91 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,16 +35,21 @@ # "numpydoc", "sphinx_design", "sphinx_favicon", + "sphinx_copybutton", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.githubpages", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", + "sphinx_gallery.gen_gallery", ] linkcheck_ignore = [ "https://doi.org/10.1021/acs.nanolett.5b00449", # 403 Client Error: Forbidden for url "https://onlinelibrary.wiley.com/doi/10.1111/j.1365-2818.2006.01549.x", # 403 Client Error: Forbidden for url + # Remove when setup + "https://github.com/hyperspy/exspy-demos", + "https://www.anaconda.com/blog/understanding-conda-and-pip", # Transcient? ] intersphinx_mapping = { @@ -125,5 +130,17 @@ } toc_object_entries_show_parents = "hide" -# def setup(app): -# app.add_css_file("custom-styles.css") +# -- Sphinx-Gallery--------------- + +# https://sphinx-gallery.github.io +sphinx_gallery_conf = { + "examples_dirs": "../examples", # path to your example scripts + "gallery_dirs": "auto_examples", # path to where to save gallery generated output + "filename_pattern": ".py", # pattern to define which will be executed + "ignore_pattern": "_sgskip.py", # pattern to define which will not be executed +} + +# -- Sphinx-copybutton ----------- + +copybutton_prompt_text = r">>> |\.\.\. " +copybutton_prompt_is_regexp = True diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 000000000..3345ab22f --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,6 @@ +.. _examples-index: + +Gallery of Examples +=================== + +Below is a gallery of examples. diff --git a/examples/model_fitting/EELS_curve_fitting.py b/examples/model_fitting/EELS_curve_fitting.py index d35979758..4087127c8 100644 --- a/examples/model_fitting/EELS_curve_fitting.py +++ b/examples/model_fitting/EELS_curve_fitting.py @@ -17,7 +17,7 @@ beam_energy=300, convergence_angle=24.6, collection_angle=13.6 ) -m = s.create_model(ll=ll) +m = s.create_model(low_loss=ll) m.enable_fine_structure() m.multifit(kind="smart") m.plot() diff --git a/setup.py b/setup.py index c0c6797d7..b6de47b6b 100644 --- a/setup.py +++ b/setup.py @@ -39,6 +39,7 @@ "sphinx-copybutton", "sphinx-design", "sphinx-favicon", + "sphinx-gallery", ], "tests": [ "pytest >= 5.0", From 20a236fb1653e53e941080ef6471b2943f9cd241 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 12:58:17 +0100 Subject: [PATCH 07/20] Restructure intro page to avoid repetition --- doc/index.rst | 35 +++++++++-------------------------- doc/intro.rst | 33 +++++++++++++++++++++++++-------- doc/license.rst | 14 -------------- doc/user_guide/index.rst | 1 - 4 files changed, 34 insertions(+), 49 deletions(-) delete mode 100644 doc/license.rst diff --git a/doc/index.rst b/doc/index.rst index b3046771e..55eb1edf9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,29 +1,12 @@ -Welcome to exSpy's documentation! -*********************************** -**exSpy** is a Python package extending the functionality for multi-dimensional -data analysis provided by the `HyperSpy `_ library. It is -aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS) -and Electron Energy Loss Spectroscopy (EELS). - -Check out the :ref:`installation ` section for further information, including -how to start using this project. - -.. note:: - - This is an open-source community project: everyone is welcome to contribute. - Please read our (see :ref:`contributing_label`) guidelines and get started! - -Contents -======== - .. toctree:: - :maxdepth: 2 - - user_guide/index.rst - reference/index.rst - changes.rst - Citing - contributing.rst - license.rst + :maxdepth: 1 + :hidden: + + User Guide + Examples + Reference + Release Notes + Citing + Contribute .. include:: intro.rst diff --git a/doc/intro.rst b/doc/intro.rst index 0132201f3..2cefe5299 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -1,12 +1,18 @@ +Welcome to exSpy's documentation! +*********************************** +**exSpy** is a Python package extending the functionality for multi-dimensional +data analysis provided by the `HyperSpy `_ library. It is +aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS) +and Electron Energy Loss Spectroscopy (EELS). -What is exSpy -============= +Check out the :ref:`installation ` section for further information, +including how to start using this project. -exSpy is an open source Python library which provides tools to facilitate -the visualization and processing of EELS EDS and other spectroscopic data. +.. note:: + + This is an open-source community project: everyone is welcome to contribute. + Please read our (see :ref:`contributing_label`) guidelines and get started! -exSpy is built on top of HyperSpy, a Python library for multi-dimensional -data analysis and extends it with tools for the analysis of spectroscopic data. Learning resources ================== @@ -98,7 +104,18 @@ HyperSpy in a scientific database e.g. `Google Scholar Articles published before 2012 may mention the HyperSpy project under its old name, `EELSLab`. -Credits + +License ======= -.. include:: ../AUTHORS.txt +**exSpy** is free software: you can redistribute it and/or modify +it under the terms of the `GNU General Public License (GPL) +`_ as published by +the Free Software Foundation, either version 3 of the license, or +(at your option) any later version. + +**exSpy** is distributed in the hope that it will be useful, +but **without any warranty**; without even the implied warranty of +**merchantability** or **fitness for a particular purpose**. See the +`GNU General Public License `_ +for more details. diff --git a/doc/license.rst b/doc/license.rst deleted file mode 100644 index 9fce89161..000000000 --- a/doc/license.rst +++ /dev/null @@ -1,14 +0,0 @@ -License -******* - -**exSpy** is free software: you can redistribute it and/or modify -it under the terms of the `GNU General Public License (GPL) -`_ as published by -the Free Software Foundation, either version 3 of the license, or -(at your option) any later version. - -**exSpy** is distributed in the hope that it will be useful, -but **without any warranty**; without even the implied warranty of -**merchantability** or **fitness for a particular purpose**. See the -`GNU General Public License `_ -for more details. diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 9d108c062..4ff2feb63 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -5,7 +5,6 @@ User Guide ########## .. toctree:: - :caption: User Guide :maxdepth: 2 install From 5b6f017dd00f820e6646a369c5d31f9ef57e637c Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 13:24:39 +0100 Subject: [PATCH 08/20] Simplify installation instructions --- doc/user_guide/install.rst | 353 +++++++------------------------------ 1 file changed, 63 insertions(+), 290 deletions(-) diff --git a/doc/user_guide/install.rst b/doc/user_guide/install.rst index d4904f58b..bd595ae8c 100644 --- a/doc/user_guide/install.rst +++ b/doc/user_guide/install.rst @@ -1,344 +1,117 @@ .. _install-label: -Installing exSpy -================ - -The easiest way to install exSpy is to use the -:ref:`HyperSpy Bundle `, which is available on Windows, MacOS -and Linux. - -Alternatively, exSpy can be installed in an existing python distribution, -read the :ref:`conda installation ` and -:ref:`pip installation` sections for instructions. - -.. _hyperspy-bundle: - -HyperSpy Bundle ---------------- +.. warning:: + These installation instructions are pending the release of the first version of exSpy. + In the meantime, you will need to install the development version, see instructions + below. -The `HyperSpy `__ bundle is very similar -to the Anaconda distribution, and it includes: +Installation +************ - * HyperSpy - * HyperSpyUI - * `HyperSpy extensions `_ - * context `menu shortcut (right-click) `_ - to Jupyter Notebook, Qtconsole or JupyterLab +To install exSpy, you have the following options (independent of the operating system you use): -.. raw:: html +1. exSpy is included in the `HyperSpy Bundle `_, + a standalone program that includes a python distribution and all relevant libraries + (recommended if you do not use *python* for anything else). +2. :ref:`conda` (recommended if you are also working with other *python* packages). +3. :ref:`pip`. +4. Installing the development version from `GitHub `_. + Refer to the appropriate section in the :external+hyperspy:ref:`HyperSpy user guide + ` (replacing ``hyperspy`` by ``exSpy``). -
- - Download HyperSpy-bundle installer - -
-
-For instructions, see the `HyperSpy bundle `__ repository. +.. _conda: Installation using conda ------------------------- +======================== -`Conda `_ is a package manager for Anaconda-like -distributions, such as the `Miniforge `_ -or the `HyperSpy-bundle `__. -Since HyperSpy is packaged in the `conda-forge `__ channel, -it can easily be installed using conda. +Follow these 3 steps to install exSpy using **conda** and start using it. -To install exSpy run the following from the Anaconda Prompt on Windows or -from a Terminal on Linux and Mac. +1. Creating a conda environment +------------------------------- -.. code-block:: bash +exSpy requires Python 3 and ``conda`` -- we suggest using the Python 3 version +of `Miniforge `_. - $ conda install exSpy -c conda-forge +We recommend creating a new environment for the exSpy package (or installing +it in the :external+hyperspy:ref:`HyperSpy ` +environment, if you have one already). To create a new environment: -This will also install the optional GUI packages for exSpy +1. Load the miniforge prompt. +2. Run the following command: .. code-block:: bash - $ conda install hyperspy-base -c conda-forge - -.. note:: - - Depending on how Anaconda has been installed, it is possible that the - ``conda`` command is not available from the Terminal, read the - `Anaconda User Guide `_ for details. - -.. note:: - - Using ``-c conda-forge`` is only necessary when the ``conda-forge`` channel - is not already added to the conda configuration, read the - `conda-forge documentation `_ - for more details. - -.. note:: + (base) conda create -n exspy -y - Depending on the packages installed in Anaconda, ``conda`` can be slow and - in this case ``mamba`` can be used as an alternative of ``conda`` since the - former is significantly faster. Read the - `mamba documentation `_ for instructions. -Further information -^^^^^^^^^^^^^^^^^^^ +2. Installing the package in the new environment +------------------------------------------------ -When installing packages, ``conda`` will verify that all requirements of `all` -packages installed in an environment are met. This can lead to situations where -a solution for dependencies resolution cannot be resolved or the solution may -include installing old or undesired versions of libraries. The requirements -depend on which libraries are already present in the environment as satisfying -their respective dependencies may be problematic. In such a situation, possible -solutions are: - -- use Miniconda instead of Anaconda, if you are installing a python - distribution from scratch: Miniconda only installs very few packages so satisfying - all dependencies is simple. -- install HyperSpy in a `new environment `_. - The following example illustrates how to create a new environment named ``hspy_environment``, - activate it and install HyperSpy in the new environment. +Now activate the exSpy environment and install the package from ``conda-forge``: .. code-block:: bash - $ conda create -n hspy_environment - $ conda activate hspy_environment - $ conda install hyperspy -c conda-forge - -.. note:: - - A consequence of installing hyperspy in a new environment is that you need - to activate this environment using ``conda activate environment_name`` where - ``environment_name`` is the name of the environment, however `shortcuts` can - be created using different approaches: - - - Install `start_jupyter_cm `_ - in the hyperspy environment. - - Install `nb_conda_kernels `_. - - Create `IPython kernels for different environment `_. - -To learn more about the Anaconda eco-system: + (base) conda activate exspy + (exspy) conda install -c conda-forge exspy -y -- Choose between `Anaconda or Miniconda `_? -- Understanding `conda and pip `_. -- What is `conda-forge `__. +Required dependencies will be installed automatically. -.. _install-with-pip: +Installation is completed! To start using it, check the next section. -Installation using pip ----------------------- - -HyperSpy is listed in the `Python Package Index -`_. Therefore, it can be automatically downloaded -and installed `pip `__. You may need to -install pip for the following commands to run. +.. Note:: -To install all of HyperSpy's functionalities, run: + If you run into trouble, check the more detailed documentation in the + :external+hyperspy:ref:`HyperSpy user guide `. -.. code-block:: bash - $ pip install hyperspy[all] +3. Getting Started +------------------ -To install only the strictly required dependencies and limited functionalities, -use: +To get started using exSpy, especially if you are unfamiliar with Python, we +recommend using `Jupyter notebooks `_. Having installed +exSpy as above, a Jupyter notebook can be installed and opened using the following commands +entered into an anaconda prompt (from scratch): .. code-block:: bash - $ pip install hyperspy - -See the following list of selectors to select the installation of optional -dependencies required by specific functionalities: - -* ``learning`` for some machine learning features, -* ``gui-jupyter`` to use the `Jupyter widgets `_ - GUI elements, -* ``gui-traitsui`` to use the GUI elements based on `traitsui `_, -* ``mrcz`` to read mrcz file, -* ``speed`` to speed up some functionalities, -* ``usid`` to read usid file, -* ``tests`` to install required libraries to run HyperSpy's unit tests, -* ``build-doc`` to install required libraries to build HyperSpy's documentation, -* ``dev`` to install all the above, -* ``all`` to install all the above except the development requirements - (``tests``, ``build-doc`` and ``dev``). + (base) conda activate exspy + (exspy) conda install -c conda-forge jupyterlab -y + (exspy) jupyter lab -For example: -.. code-block:: bash - - $ pip install hyperspy[learning, gui-jupyter] - -Finally, be aware that HyperSpy depends on a number of libraries that usually -need to be compiled and therefore installing HyperSpy may require development -tools installed in the system. If the above does not work for you remember that -the easiest way to install HyperSpy is -:ref:`using the HyperSpy bundle `. - -.. _update-with-conda: - -Update HyperSpy ---------------- - -Using conda -^^^^^^^^^^^ - -To update hyperspy to the latest release using conda: - -.. code-block:: bash - - $ conda update hyperspy -c conda-forge - -Using pip -^^^^^^^^^ - -To update hyperspy to the latest release using pip: - -.. code-block:: bash - - $ pip install hyperspy --upgrade - -Install specific version ------------------------- - -Using conda -^^^^^^^^^^^ - -To install a specific version of hyperspy (for example ``1.6.1``) using conda: - -.. code-block:: bash +.. _pip: - $ conda install hyperspy=1.6.1 -c conda-forge - -Using pip -^^^^^^^^^ - -To install a specific version of hyperspy (for example ``1.6.1``) using pip: - -.. code-block:: bash - - $ pip install hyperspy==1.6.1 - - -.. _install-rolling: - -Rolling release Linux distributions ------------------------------------ - -Due to the requirement of up to date versions for dependencies such as *numpy*, -*scipy*, etc., binary packages of HyperSpy are not provided for most linux -distributions and the installation via :ref:`Anaconda/Miniconda ` -or :ref:`Pip ` is recommended. - -However, packages of the latest HyperSpy release and the related -GUI packages are maintained for the rolling release distributions -*Arch-Linux* (in the `Arch User Repository -`_) (AUR) and -*openSUSE* (`Community Package `_) -as ``python-hyperspy`` and ``python-hyperspy-gui-traitsui``, -``python-hyperspy-gui-ipywidgets`` for the GUIs packages. - -A more up-to-date package that contains all updates to be included -in the next minor version release (likely including new features compared to -the stable release) is also available in the AUR as |python-hyperspy-git|_. - -.. |python-hyperspy-git| replace:: ``python-hyperspy-git`` -.. _python-hyperspy-git: https://aur.archlinux.org/packages/python-hyperspy-git - -.. _install-dev: - -Install development version ---------------------------- - -Clone the hyperspy repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To get the development version from our git repository you need to install `git -`_. Then just do: - -.. code-block:: bash - - $ git clone https://github.com/hyperspy/hyperspy.git - -.. Warning:: - - When running hyperspy from a development version, it can happen that the - dependency requirement changes in which you will need to keep this - this requirement up to date (check dependency requirement in ``setup.py``) - or run again the installation in development mode using ``pip`` as explained - below. - -Installation in a Anaconda/Miniconda distribution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Optionally, create an environment to separate your hyperspy installation from -other anaconda environments (`read more about environments here -`_): - -.. code-block:: bash - - $ conda create -n hspy_dev python # create an empty environment with latest python - $ conda activate hspy_dev # activate environment - -Install the runtime and development dependencies requirements using conda: - -.. code-block:: bash - - $ conda install hyperspy-base -c conda-forge --only-deps # install hyperspy dependencies - $ conda install hyperspy-dev -c conda-forge # install developer dependencies - -The package ``hyperspy-dev`` will install the development dependencies required -for testing and building the documentation. - -From the root folder of your hyperspy repository (folder containing the -``setup.py`` file) run `pip `_ in development mode: - -.. code-block:: bash - - $ pip install -e . --no-deps # install the currently checked-out branch of hyperspy - -Installation in other (non-system) Python distribution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Installation using pip +====================== -From the root folder of your hyperspy repository (folder containing the -``setup.py`` file) run `pip `_ in development mode: +Alternatively, you can also find exSpy in the `Python Package Index (PyPI) `_ +and install it using (requires ``pip``): .. code-block:: bash - $ pip install -e .[dev] - -All required dependencies are automatically installed by pip. If you don't want -to install all dependencies and only install some of the optional dependencies, -use the corresponding selector as explained in the :ref:`install-with-pip` section + pip install exspy -.. - If using Arch Linux, the latest checkout of the master development branch - can be installed through the AUR by installing the `hyperspy-git package - `_ +Required dependencies will be installed automatically. -Installation in a system Python distribution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When using a system Python distribution, it is recommended to install the -dependencies using your system package manager. +Updating the package +==================== -From the root folder of your hyperspy repository (folder containing the -``setup.py`` file) run `pip `_ in development mode. +Using **conda**: .. code-block:: bash - $ pip install -e --user .[dev] - -.. _create-debian-binary: - -Creating Debian/Ubuntu binaries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + conda update exspy -c conda-forge -You can create binaries for Debian/Ubuntu from the source by running the -`release_debian` script +Using **pip**: .. code-block:: bash - $ ./release_debian + pip install exspy --upgrade -.. Warning:: +.. Note:: - For this to work, the following packages must be installed in your system - python-stdeb, debhelper, dpkg-dev and python-argparser are required. + If you want to be notified about new releases, please *Watch (Releases only)* the `exSpy repository + on GitHub `_ (requires a GitHub account). From ba3203851a67f821a3da2a3e8941e6040a055a11 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 13:49:26 +0100 Subject: [PATCH 09/20] Simplify docs build workflow to make PR comments of the sphinx warning --- .github/workflows/docs.yml | 42 +++++++++++--------------------------- 1 file changed, 12 insertions(+), 30 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 97c48edd0..0c64df58e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,31 +3,10 @@ name: Docs on: [push, pull_request] jobs: - build_doc_PR: - # This build is to automatically add comments on PR - name: PR comments - runs-on: ubuntu-latest - env: - BUILD_DEPS: python3-dev build-essential graphviz - LATEX_DEPS: dvipng latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended - - steps: - - uses: actions/checkout@v4 - - - uses: ericpre/sphinx-action@latest_sphinx - with: - pre-build-command: "apt-get update -y && apt-get install -y ${{ env.BUILD_DEPS }} ${{ env.LATEX_DEPS }} && pip install .'[doc]'" - build-command: make html - docs-folder: doc/ - - - uses: actions/upload-artifact@v3 - with: - path: ./doc/_build/html/ - name: docs_build - build_docs: - # This build is to check links and update table of supported formats - name: Check links + # This build is to make PR comments for the sphinx warning and check if + # web links are not broken + name: Check links and make PR comments runs-on: ubuntu-latest env: DOCS_PATH: ./doc/_build/html/ @@ -45,12 +24,9 @@ jobs: shell: bash -l {0} run: | pip install .'[doc]' - - - name: Check links - shell: bash -l {0} - run: | - cd doc - make linkcheck + + # Add sphinx warnings as PR comments + - uses: sphinx-doc/sphinx-problem-matcher@master - name: Build docs shell: bash -l {0} @@ -63,6 +39,12 @@ jobs: path: ${{ env.DOCS_PATH }} name: docs_html + - name: Check links + shell: bash -l {0} + run: | + cd doc + make linkcheck + push_docs: # This build is to push changes to gh-pages branch (https://hyperspy.org/exspy) needs: build_docs From 5c2560e2434507b0998038a3b00791389272d9ee Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 13:57:34 +0100 Subject: [PATCH 10/20] Fix linkcheck doc build --- doc/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 1c014eb91..7c4ea7c78 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -50,6 +50,9 @@ # Remove when setup "https://github.com/hyperspy/exspy-demos", "https://www.anaconda.com/blog/understanding-conda-and-pip", # Transcient? + # Remove once it is merged and the links are working + "https://exspy.readthedocs.io", + "https://github.com/hyperspy/exspy/blob/main/releasing_guide.md", ] intersphinx_mapping = { From a84145b3f010c77e44cdaf41e519ad691d950126 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 14:09:36 +0100 Subject: [PATCH 11/20] Use pytest-xdist and 2 workers on CI when running the test suite --- .github/workflows/tests.yml | 2 +- pyproject.toml | 6 +++++- setup.py | 1 + 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 5f5f49217..6f1e9ba53 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -45,7 +45,7 @@ jobs: - name: Run test suite run: | - pytest --pyargs exspy + pytest --pyargs exspy -n 2 - name: Upload coverage to Codecov if: ${{ always() }} diff --git a/pyproject.toml b/pyproject.toml index fb58f9eb1..99ed3d685 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,4 +2,8 @@ force-exclude = ''' exspy/misc/eds/ffast_mac.py | exspy/misc/elements.py -''' \ No newline at end of file +''' + +[tool.pytest.ini_options] +addopts = "-ra -n auto --dist loadfile" +testpaths = ["hyperspy/tests", ] diff --git a/setup.py b/setup.py index b6de47b6b..50a330c82 100644 --- a/setup.py +++ b/setup.py @@ -45,6 +45,7 @@ "pytest >= 5.0", "pytest-mpl", "pytest-cov >= 2.8.1", + "pytest-xdist", ], "dev": ["black", "pre-commit >=1.16"], } From 36727d4b201141a23c8639bf7be5e7a4606c1db9 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 14:16:02 +0100 Subject: [PATCH 12/20] Add `all` selector for installation to install gui libraries --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index 50a330c82..e37af0a1b 100644 --- a/setup.py +++ b/setup.py @@ -48,6 +48,7 @@ "pytest-xdist", ], "dev": ["black", "pre-commit >=1.16"], + "all": ["gui-jupyter", "gui-traitsui"], } From ba36b3bc48a3bbe8335738274928950b9e73ebd9 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 14:33:22 +0100 Subject: [PATCH 13/20] Add `README.md` --- README.md | 14 ++++++++++++++ README.rst | 0 2 files changed, 14 insertions(+) create mode 100644 README.md delete mode 100644 README.rst diff --git a/README.md b/README.md new file mode 100644 index 000000000..fb891cf77 --- /dev/null +++ b/README.md @@ -0,0 +1,14 @@ + +**exSpy** is a Python package extending the functionality for multi-dimensional +data analysis provided by the [HyperSpy](https://hyperspy.org) library. It is +aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS) +and Electron Energy Loss Spectroscopy (EELS). + +Go to the documentation for instructions on how to install exSpy and start an +analysis: [Read the docs](https://exspy.readthedocs.io). + +Everyone is welcome to contribute. Please read our +[contributing guidelines](https://github.com/hyperspy/exspy/blob/main/CONTRIBUTING.rst) and get started! + +Development of exSpy is documented in the +[changelog](https://github.com/hyperspy/exspy/blob/main/CHANGES.rst). diff --git a/README.rst b/README.rst deleted file mode 100644 index e69de29bb..000000000 From 80872ab901ab720b294ac8ca754f5150d41cedc3 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 14:45:05 +0100 Subject: [PATCH 14/20] Add `README.md` and add run `twine check` on dist files in the build workflow --- .github/workflows/build.yml | 8 ++++++-- setup.py | 5 +++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0b1171db7..278104d73 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -21,9 +21,9 @@ jobs: python --version pip --version - - name: Install pypa/build + - name: Install pypa/build pypa/twine run: | - pip install build + pip install build twine - name: Build a binary wheel and a source tarball run: | @@ -32,6 +32,10 @@ jobs: - name: Display content dist folder run: | ls -l dist/ + + - name: Run twin check + run: | + twine check dist/* - uses: actions/upload-artifact@v3 with: diff --git a/setup.py b/setup.py index e37af0a1b..ca22c17d4 100644 --- a/setup.py +++ b/setup.py @@ -59,7 +59,8 @@ author=author, license=license, url="https://github.com/pyxem/pyxem", - long_description=open("README.rst").read(), + long_description=open("README.md").read(), + long_description_content_type="text/markdown", keywords=[ "data analysis", "microscopy", @@ -98,7 +99,7 @@ ], python_requires="~=3.8", package_data={ - "": ["LICENSE", "README.rst"], + "": ["LICENSE", "README.md"], "exspy": [ "data/*hspy", "test/drawing/data/*hspy", From a66e90c79b742edf8703719292757b39316b32f3 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 15:45:20 +0100 Subject: [PATCH 15/20] Fix installation gui packages when using `all` selector --- setup.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup.py b/setup.py index ca22c17d4..2bb7370b3 100644 --- a/setup.py +++ b/setup.py @@ -47,8 +47,8 @@ "pytest-cov >= 2.8.1", "pytest-xdist", ], - "dev": ["black", "pre-commit >=1.16"], - "all": ["gui-jupyter", "gui-traitsui"], + "dev": ["black"], + "all": ["exspy[gui-jupyter]", "exspy[gui-traitsui]"], } From 81e5c7df4d95d74ba720968768f9e31209327203 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 15:46:08 +0100 Subject: [PATCH 16/20] Fix package metadata and set `__version__` --- exspy/__init__.py | 2 ++ exspy/_version.py | 1 + exspy/release_info.py | 6 ------ pyproject.toml | 4 ++++ setup.py | 19 +++++++++---------- 5 files changed, 16 insertions(+), 16 deletions(-) create mode 100644 exspy/_version.py delete mode 100644 exspy/release_info.py diff --git a/exspy/__init__.py b/exspy/__init__.py index 181d85404..3751b05a4 100644 --- a/exspy/__init__.py +++ b/exspy/__init__.py @@ -4,9 +4,11 @@ from . import signals from .misc import material from ._defaults_parser import preferences +from ._version import __version__ __all__ = [ + "__version__", "components", "data", "preferences", diff --git a/exspy/_version.py b/exspy/_version.py new file mode 100644 index 000000000..f102a9cad --- /dev/null +++ b/exspy/_version.py @@ -0,0 +1 @@ +__version__ = "0.0.1" diff --git a/exspy/release_info.py b/exspy/release_info.py deleted file mode 100644 index 98d057d28..000000000 --- a/exspy/release_info.py +++ /dev/null @@ -1,6 +0,0 @@ -name = "exspy" -version = "0.0.1" -author = "exSpy Developers" -copyright = "Copyright 2007-2023, The exSpy developers" -license = "GPLv3+" -status = "development" diff --git a/pyproject.toml b/pyproject.toml index 99ed3d685..07370abbe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,7 @@ +[build-system] +requires = ["setuptools>=40.8.0", "wheel"] +build-backend = "setuptools.build_meta" + [tool.black] force-exclude = ''' exspy/misc/eds/ffast_mac.py diff --git a/setup.py b/setup.py index 2bb7370b3..dace3ea1a 100644 --- a/setup.py +++ b/setup.py @@ -19,11 +19,6 @@ from setuptools import setup, find_packages -exec(open("exspy/release_info.py").read()) # grab version info - -# Projects with optional features for building the documentation and running -# tests. From setuptools: -# https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies extra_feature_requirements = { "gui-jupyter": [ @@ -52,12 +47,16 @@ } +version = {} +with open("exspy/_version.py") as fp: + exec(fp.read(), version) + + setup( - name=name, - version=version, - description="multi-dimensional diffraction microscopy", - author=author, - license=license, + name="exspy", + version=version["__version__"], + description="EELS and EDS analysis with the HyperSpy framework", + license="LICENSE", url="https://github.com/pyxem/pyxem", long_description=open("README.md").read(), long_description_content_type="text/markdown", From 6a6fcf4b95df1169c60929744c440bbec093df89 Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 19:58:03 +0100 Subject: [PATCH 17/20] Setup codecov --- .github/workflows/tests.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 6f1e9ba53..a4599f132 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -50,3 +50,5 @@ jobs: - name: Upload coverage to Codecov if: ${{ always() }} uses: codecov/codecov-action@v3 + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} From c9f4aa9c0de0489ecaf88c99fdb40b8c3cbe6f2a Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 20:08:17 +0100 Subject: [PATCH 18/20] Update .gitignore --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 4f21eef4b..ccb49562c 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,7 @@ doc/_build/* doc/auto_examples/* build/* dist/* -*egg-info* \ No newline at end of file +*egg-info* +*.pyc +.spyproject/* +*__pycache__* \ No newline at end of file From ede024b55f5eb798e805a24b3d4381ac0ee2280b Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 20:36:01 +0100 Subject: [PATCH 19/20] run coverage --- .github/workflows/tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a4599f132..9333cb5d9 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -45,7 +45,7 @@ jobs: - name: Run test suite run: | - pytest --pyargs exspy -n 2 + pytest --pyargs exspy -n 2 --cov=. --cov-report=xml - name: Upload coverage to Codecov if: ${{ always() }} From e2c7e9e02e854f56a9f023c074ad6332da1fbc7a Mon Sep 17 00:00:00 2001 From: Eric Prestat Date: Sun, 29 Oct 2023 20:05:35 +0100 Subject: [PATCH 20/20] Add docs, github actions and codecov badges --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index fb891cf77..c24ecc4e2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ +[![Tests](https://github.com/hyperspy/exspy/actions/workflows/tests.yml/badge.svg)](https://github.com/hyperspy/exspy/actions/workflows/tests.yml) +[![Docs](https://readthedocs.org/projects/exspy/badge/?version=latest)](https://exspy.readthedocs.io/en/latest/?badge=latest) +[![codecov](https://codecov.io/gh/hyperspy/exspy/graph/badge.svg?token=X7T3LE121Q)](https://codecov.io/gh/hyperspy/exspy) +[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) + **exSpy** is a Python package extending the functionality for multi-dimensional data analysis provided by the [HyperSpy](https://hyperspy.org) library. It is aimed at helping with the analysis of X-rays Energy Dispersive Spectroscopy (EDS)