Publish package (#277)

Merge PR #277: Project Enhancements and Workflow Updates

This pull request introduces several improvements to the project:

1. **Documentation Enhancements:**
   - Dependencies for documentation are now in a separate section in the toml file, ensuring they are not packaged for users.
   - Updated the documentation structure to prioritize README and tutorials.
   - Improved shields in the README for better visibility and accuracy.
   - Updated the license to reflect the current year.

2. **Workflow Updates:**
   - Renamed the documentation workflow for a more informative shield.
   - Modified the workflow to run on the main branch, ensuring it stays up-to-date.
   - Adjusted workflow dependencies to let other workflows complete before merging.

3. **Package Versioning:**
   - Implemented a workflow that runs a prerelease job on every push to the main branch and a release job on every tag push.
   - A publish to PyPI job is executed on every successful prerelease or release job.
   - If publish is successful, the version is updated in the pyproject.toml file and pushed to the main branch.

These changes enhance the project's maintainability, versioning, and overall user experience.

[Link to prerelease example run](https://github.com/OpenCOMPES/sed/actions/runs/6897868624)
[Link to release example run](https://github.com/OpenCOMPES/sed/actions/runs/6898553103)
[Link to this PR](#266)

.github/workflows/build_deploy_docs.yml → .github/workflows/documentation.yml

@@ -45,8 +45,8 @@ jobs:
           python-version: 3.8
           poetry-version: 1.2.2
 
-      - name: Install docs and notebook dependencies
-        run: poetry install -E notebook -E docs
+      - name: Install notebook dependencies
+        run: poetry install -E notebook --with docs
 
       - name: Install pandoc
         run: |

.github/workflows/release.yml

@@ -0,0 +1,155 @@
+name: Publish to PyPI
+
+# Workflow runs prerelease job on every push to main branch
+# and a release job on every tag push.
+# A publish job is executed on every successful prerelease or release job
+# And if publish is successful, the version is also updated in the pyproject.toml file and pushed to main branch
+  # By default, a workflow run that is triggered by a push event will
+  # not trigger another push event when it pushes changes to the repository.
+# The package is distributed as sed-processor
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+
+jobs:
+  prerelease:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          lfs: true
+          path: 'sed-processor'
+
+      - name: "Setup Python, Poetry and Dependencies"
+        uses: zain-sohail/action-setup-cache-python-poetry@main
+        with:
+          python-version: 3.8
+          poetry-version: 1.2.2
+          working-directory: sed-processor
+
+      - name: Change to distribution name in toml file
+        run: |
+          cd sed-processor
+          sed -i 's/name = "sed"/name = "sed-processor"/' pyproject.toml
+
+      - name: bump pre-release version
+        id: version
+        working-directory: sed-processor
+        run: |
+          VERSION=$(poetry version -s prerelease)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          poetry build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist
+          path: sed-processor/dist
+
+      - name: Upload pyproject.toml
+        uses: actions/upload-artifact@v3
+        with:
+          name: pyproject
+          path: sed-processor/pyproject.toml
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          lfs: true
+          path: 'sed-processor'
+
+      - name: "Setup Python, Poetry and Dependencies"
+        uses: zain-sohail/action-setup-cache-python-poetry@main
+        with:
+          python-version: 3.8
+          poetry-version: 1.2.2
+          working-directory: sed-processor
+
+      - name: Change to distribution name in toml file
+        run: |
+          cd sed-processor
+          sed -i 's/name = "sed"/name = "sed-processor"/' pyproject.toml
+
+      - name: Bump release version and build
+        id: version
+        working-directory: sed-processor
+        run: |
+          VERSION=$(echo ${GITHUB_REF#refs/tags/v} | sed 's/-.*//')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          poetry version $VERSION
+          poetry build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: dist
+          path: sed-processor/dist
+
+      - name: Upload pyproject.toml
+        uses: actions/upload-artifact@v3
+        with:
+          name: pyproject
+          path: sed-processor/pyproject.toml
+
+  publish:
+    needs: [prerelease, release]
+    if: always() && (needs.prerelease.result == 'success' || needs.release.result == 'success')
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ needs.prerelease.outputs.version || needs.release.outputs.version }}
+    environment:
+        name: pypi
+        url: https://pypi.org/p/sed-processor
+    permissions:
+        id-token: write
+
+    steps:
+      - name: Download a single artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: dist
+
+      - name: Publish package distributions to PyPI Test
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: .
+
+  bump-version:
+    needs: publish
+    if: always() && (needs.publish.result == 'success')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          lfs: true
+          path: 'sed-processor'
+
+      - name: Download pyproject.toml
+        uses: actions/download-artifact@v3
+        with:
+          name: pyproject
+          path: sed-processor
+
+      # new_branch set for cases when tagging a release
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v9
+        with:
+          default_author: github_actions
+          message: 'bump version to ${{ needs.publish.outputs.version  }}'
+          add: pyproject.toml
+          cwd: sed-processor
+          new_branch: main
+          # By default, a workflow run that is triggered by a push event will
+          # not trigger another push event when it pushes changes to the repository.
+          # So no problem here.

.github/workflows/testing_coverage.yml

@@ -25,12 +25,12 @@ jobs:
         with:
           python-version: 3.8
           poetry-version: 1.2.2
-  
+
       # Run pytest with coverage report, saving to xml
       - name: Run tests on python 3.8
         run: |
           poetry run pytest --cov --cov-report xml:cobertura.xml --full-trace --show-capture=no -sv -n auto tests/
-      
+
       # Take report and upload to coveralls
       - name: Coveralls
         uses: coverallsapp/github-action@v2

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 OpenCOMPES
+Copyright (c) 2022-2023 OpenCOMPES
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,61 +1,94 @@
-# sed
-[![Documentation Status](https://github.com/OpenCOMPES/sed/actions/workflows/build_deploy_docs.yml/badge.svg)](https://opencompes.github.io/sed/)
+[![Documentation Status](https://github.com/OpenCOMPES/sed/actions/workflows/documentation.yml/badge.svg)](https://opencompes.github.io/sed/)
 ![](https://github.com/OpenCOMPES/sed/actions/workflows/linting.yml/badge.svg?branch=main)
 ![](https://github.com/OpenCOMPES/sed/actions/workflows/testing_multiversion.yml/badge.svg?branch=main)
-![](https://img.shields.io/pypi/pyversions/sedprocessor)
-![](https://img.shields.io/pypi/l/sedprocessor)
-![](https://img.shields.io/pypi/v/sedprocessor)
+![](https://img.shields.io/pypi/pyversions/sed-processor)
+![](https://img.shields.io/pypi/l/sed-processor)
+[![](https://img.shields.io/pypi/v/sed-processor)](https://pypi.org/project/sed-processor)
 [![Coverage Status](https://coveralls.io/repos/github/OpenCOMPES/sed/badge.svg?branch=main&kill_cache=1)](https://coveralls.io/github/OpenCOMPES/sed?branch=main)
 
+# Single Event Data Frame Processor
 
-Single Event Data Frame Processor: Backend to handle photoelectron resolved datastreams
+Backend to handle photoelectron resolved datastreams.
 
-# Installation
+## Installation
 
-## Conda approach
+### Pip (for users)
 
-Clone this repository and cd to its root folder.
-Create a new environment by typing:
+- Create a new virtual environment using either venv, pyenv, conda, etc. See below for an example.
+
+```bash
+python -m venv .sed-venv
 ```
-conda env create -f env.yml
+
+- Activate your environment:
+
+```bash
+source .sed-venv/bin/activate
 ```
-This should install all the requirements to run `sed` in your environment.
-To activate your environment:
+
+- Install `sed`, distributed as `sed-processor` on PyPI:
+
+```bash
+pip install sed-processor
 ```
-conda activate sed_conda
+
+- This should install all the requirements to run `sed` in your environment.
+
+- If you intend to work with Jupyter notebooks, it is helpful to install a Jupyter kernel for your environment. This can be done, once your environment is activated, by typing:
+
+```bash
+python -m ipykernel install --user --name=sed_kernel
 ```
-If you intend to work with jupyter notebooks, it is helpfull to install a jupyter kernel of your environment. This can be done, once activating your environment, by typing:
+### For Contributors
+
+To contribute to the development of `sed`, you can follow these steps:
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/OpenCOMPES/sed.git
+cd sed
 ```
-python -m ipykernel install --user --name=sed_conda
+
+2. Install the repository in editable mode:
+
+```bash
+pip install -e .
 ```
 
+Now you have the development version of `sed` installed in your local environment. Feel free to make changes and submit pull requests.
 
-## Poetry approach (better, but more complex)
+### Poetry (for maintainers)
 
 - Prerequisites:
-  + poetry: https://python-poetry.org/docs/
-  + pyenv: https://github.com/pyenv/pyenv
+  + Poetry: https://python-poetry.org/docs/
 
-- Clone this repository and check the python version within the `[tool.poetry.dependencies]` section of the `pyproject.toml` file
-  + If your system is using a different Python version, use `pyenv` to create and activate a Python version compatible with the specifications from the `pyproject.toml`. See [pyenv basic usage](https://github.com/pyenv/pyenv)
 - Create a virtual environment by typing:
-```python
+
+```bash
 poetry shell
 ```
-  + A new shell will be spawn with the new environment activated
+
+- A new shell will be spawned with the new environment activated.
 
 - Install the dependencies from the `pyproject.toml` by typing:
-```python
-poetry install
+
+```bash
+poetry install --with dev, docs
 ```
 
-- If you wish to use the virtual environment created by poetry to work in a Jupyter notebook, you first need to install the optional notebook dependencies and then create a Jupyter kernel for that.
-  + Install the optional dependencies ipykernel and jupyter
-  ```python
+- If you wish to use the virtual environment created by Poetry to work in a Jupyter notebook, you first need to install the optional notebook dependencies and then create a Jupyter kernel for that.
+
+  + Install the optional dependencies `ipykernel` and `jupyter`:
+
+  ```bash
   poetry install -E notebook
   ```
-  + Make sure to run the command below within your virtual environment ('poetry run' ensures this) by typing:
-  ```python
+
+  + Make sure to run the command below within your virtual environment (`poetry run` ensures this) by typing:
+
+  ```bash
   poetry run ipython kernel install --user --name=sed_poetry
   ```
-  + The new kernel will be eligible now from your kernels list in Jupyter
+
+  + The new kernel will now be available in your Jupyter kernels list.