Migrate to pyproject.toml, activate towncrier, update release workflow

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,7 +16,8 @@ A few sentences and/or a bulleted list to describe and motivate the change:
 - [ ] docstring updated (if appropriate),
 - [ ] update user guide (if appropriate),
 - [ ] added tests,
-- [ ] added line to CHANGELOG.rst,
+- [ ] add a changelog entry in the `upcoming_changes` folder (see [`upcoming_changes/README.rst`](https://github.com/lumispy/lumispy/blob/main/upcoming_changes/README.rst)),
+- [ ] Check formatting of the changelog entry (and eventual user guide changes) in the `docs/readthedocs.org:lumispy` build of this PR (link in github checks),
 - [ ] ready for review.
 
 ### Minimal example of the bug fix or the new feature

.github/workflows/doc.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Install build docs
         shell: bash -l {0}
         run: |
-          pip install .[build-doc]
+          pip install .[doc]
 
       # Add sphinx warnings as PR comments
       - uses: sphinx-doc/sphinx-problem-matcher@master

.github/workflows/package_and_test.yml

@@ -0,0 +1,10 @@
+name: Package & Test
+
+on: [push, pull_request]
+
+jobs:
+  package_and_test:
+    # Use the "reusable workflow" from the hyperspy organisation
+    uses: hyperspy/.github/.github/workflows/package_and_test.yml@main
+    with:
+      ORGANISATION: lumispy

.github/workflows/release.yml

@@ -1,4 +1,9 @@
 name: Release
+# Reusable workflows are not supported with trusted publisher
+# https://github.com/pypa/gh-action-pypi-publish/issues/166
+# copy and paste "jobs" from
+# https://github.com/hyperspy/.github/blob/main/.github/workflows/release_pure_python.yml
+
 # This workflow builds the wheels "on tag".
 # If run from the lumispy/lumispy repository, the wheels will be uploaded to pypi ;
 # otherwise, the wheels will be available as a github artefact.
@@ -11,82 +16,45 @@ on:
     - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
 
 jobs:
-  create_release:
+  package_and_test:
+    name: Package and Test
+    # Use the "reusable workflow" from the hyperspy organisation
+    uses: hyperspy/.github/.github/workflows/package_and_test.yml@main
+    with:
+      ORGANISATION: lumispy
+
+  upload_to_pypi:
+    needs: [package_and_test]
+    runs-on: ubuntu-latest
+    environment: release
+    name: Upload to pypi
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+    - name: Download dist
+      uses: actions/download-artifact@v4
+
+    - name: Display downloaded files
+      run: |
+        ls -shR
+      working-directory: dist
+
+    - uses: pypa/gh-action-pypi-publish@release/v1
+      if: ${{ startsWith(github.ref, 'refs/tags/') && github.repository_owner == 'lumispy' }}
+      # See https://docs.pypi.org/trusted-publishers/using-a-publisher/
+
+  create_github_release:
+    # If zenodo is set up to create a DOI automatically on a GitHub release,
+    # this step will trigger the mining of the DOI
+    needs: upload_to_pypi
     permissions:
       contents: write
-    name: Create Release
+    name: Create GitHub Release
     runs-on: ubuntu-latest
-    outputs: 
-      upload_url: ${{ steps.create_release.outputs.upload_url }}
-      VERSION: ${{ env.VERSION }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
       - name: Create Release
-        id: create_release
-        uses: softprops/action-gh-release@3198ee18f814cdf787321b4a32a26ddbf37acc52
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
-        with:
-          draft: false
-          prerelease: false
-      - name: Get version (on tag)
-        id: get_version
-        if: startsWith(github.ref, 'refs/tags/')
-        run: |
-          echo "VERSION=${GITHUB_REF#refs/*/v}" >> $GITHUB_ENV
-          echo "SETUP_VERSION=$(python setup.py --version)" >> $GITHUB_ENV
-      - name: Check version
-        if: ${{env.VERSION != env.SETUP_VERSION}}
-        run: |
-            echo "Version mismatch between pushed tag ($VERSION) and `release_info.py` ($SETUP_VERSION)"
-            exit 1
-
-  build_wheels_linux:
-    name: Wheels on ubuntu-latest
-    needs: create_release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.11
-
-      - name: Install release dependencies
-        run: |
-          python -m pip install twine wheel
-
-      - name: Build source distribution
-        run: |
-          python setup.py sdist bdist_wheel
-
-      - name: Display content dist folder
-        run: |
-          ls dist/
-
-      - name: Install and test distribution
-        env:
-          MPLBACKEND: agg
-        run: |
-          pip install --pre --find-links dist lumispy[tests]
-          pytest --pyargs lumispy
-
-      - uses: actions/upload-artifact@v4
-        with:
-          path: |
-            ./dist/*.whl
-            ./sdist/*.tar.gz
-
-      - name: Publish wheels to PyPI
-        if: github.repository_owner == 'lumispy'
-        env:
-          # Github secret set in the lumispy/lumispy repository
-          # Not available from fork or pull request
-          # Secrets are not passed to workflows that are triggered by a pull request from a fork
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: |
-          twine upload dist/*.whl --verbose 
-          twine upload dist/*.tar.gz --verbose 
+        if: ${{ startsWith(github.ref, 'refs/tags/') && github.repository_owner == 'lumispy' }}
+        uses: softprops/action-gh-release@9d7c94cfd0a1f3ed45544c887983e9fa900f0564

.readthedocs.yaml

@@ -10,19 +10,22 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow || true
 
-## Build documentation in the docs/ directory with Sphinx
+# 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: all
-
+formats:
+  - htmlzip
 
 python:
-   install:
-      - method: pip
-        path: .
-        extra_requirements:
-           - build-doc
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
 

CHANGELOG.rst

@@ -6,13 +6,14 @@ All notable changes to this project will be documented in this file.
 The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
 and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
-UNRELEASED
-==========
-Changed
--------
+Changelog entries for the development version are available at
+https://lumispy.readthedocs.io/en/latest/changelog.html
+
+
+.. towncrier-draft-entries:: |release| [UNRELEASED]
+
+.. towncrier release notes start
 
-Maintenance
------------
 - Fix intersphinx links to documentation of HyperSpy 2.0 and add linkchecker workflow
 - Align supported python versions (3.8-3.12) to HyperSpy 2.0 
 

conda_environment_dev.yml

@@ -7,4 +7,6 @@ dependencies:
 - pytest-cov
 - pytest-faulthandler
 - pytest-xdist
+- hyperspy-base
+- setuptools-scm
 

doc/conf.py

@@ -3,18 +3,25 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here.
 import sys
+from datetime import datetime
+from importlib.metadata import version as get_version
 
 sys.path.append("../")
 
 
 # -- Project information
-from lumispy import release_info
-
 project = "LumiSpy"
-version = release_info.version
-release = release_info.version
-author = release_info.author
-copyright = release_info.copyright
+copyright = f"2019-{datetime.today().year}, The LumiSpy developers"
+author = "The LumiSpy developers"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
+release = get_version("lumispy")
+# The short X.Y version.
+version = ".".join(release.split(".")[:2])
 
 # -- General configuration
 
@@ -27,6 +34,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.graphviz",
     "sphinx.ext.autosummary",
+    "sphinxcontrib.towncrier",
     "sphinx_copybutton",
 ]
 
@@ -109,3 +117,11 @@ def setup(app):
     app.connect("builder-inited", run_apidoc)
     app.add_css_file("css/dark.css")
     app.add_css_file("css/light.css")
+
+
+# -- Options for towncrier_draft extension -----------------------------------
+
+# Options: draft/sphinx-version/sphinx-release
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = False
+towncrier_draft_working_directory = ".."

lumispy/__init__.py

@@ -17,31 +17,45 @@
 # along with LumiSpy. If not, see <https://www.gnu.org/licenses/#GPL>.
 
 
-import logging
-
-_logger = logging.getLogger(__name__)
+from importlib.metadata import version
+from pathlib import Path
 
 from lumispy.utils.axes import nm2eV, eV2nm, nm2invcm, invcm2nm, join_spectra
 from lumispy.utils.io import to_array, savetxt
+from lumispy import signals, components, utils
+
+__version__ = version("lumispy")
+
+# For development version, `setuptools_scm` will be used at build time
+# to get the dev version, in case of missing vcs information (git archive,
+# shallow repository), the fallback version defined in pyproject.toml will
+# be used
 
-from lumispy import signals
-from lumispy import components
-from lumispy import utils
+# If we have an editable installed from a git repository try to use
+# `setuptools_scm` to find a more accurate version:
+# `importlib.metadata` will provide the version at installation
+# time and for editable version this may be different
 
-from . import release_info
+# we only do that if we have enough git history, e.g. not shallow checkout
+_root = Path(__file__).resolve().parents[1]
+if (_root / ".git").exists() and not (_root / ".git/shallow").exists():
+    try:
+        # setuptools_scm may not be installed
+        from setuptools_scm import get_version
+
+        __version__ = get_version(_root)
+    except ImportError:  # pragma: no cover
+        # setuptools_scm not install, we keep the existing __version__
+        pass
 
 
 __all__ = [
+    "__version__",
     "components",
     "signals",
     "utils",
 ]
 
-__version__ = release_info.version
-__author__ = release_info.author
-__copyright__ = release_info.copyright
-__credits__ = release_info.credits
-__license__ = release_info.license
-__maintainer__ = release_info.maintainer
-__email__ = release_info.email
-__status__ = release_info.status
+
+def __dir__():
+    return sorted(__all__)

lumispy/signals/cl_spectrum.py

@@ -77,7 +77,7 @@ def remove_spikes(
         add_noise=False,
         navigation_mask=None,
         interactive=False,
-        **kwargs
+        **kwargs,
     ):
         if luminescence_roi is not None and signal_mask is not None:
             raise AttributeError(
@@ -102,7 +102,7 @@ def remove_spikes(
             threshold=threshold,
             interactive=interactive,
             add_noise=add_noise,
-            **kwargs
+            **kwargs,
         )
 
         if threshold == "auto":