Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/main' into sxp_fixes-for-new-daq
Browse files Browse the repository at this point in the history
  • Loading branch information
rettigl committed Nov 11, 2024
2 parents 39669d7 + 8f5e392 commit 439844b
Show file tree
Hide file tree
Showing 24 changed files with 662 additions and 495 deletions.
2 changes: 2 additions & 0 deletions .cspell/custom-dictionary.txt
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,7 @@ ptargs
pullrequest
pval
pyarrow
pydata
pyenv
pygments
pynxtools
Expand Down Expand Up @@ -371,6 +372,7 @@ utime
varnames
venv
verts
viewcode
vmax
voxels
VTOF
Expand Down
113 changes: 79 additions & 34 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ on:
# Triggers the workflow on push but only for the main branch
push:
branches: [ main ]
tags: [ v* ]
paths:
- sed/**/*
- tutorial/**
Expand All @@ -11,18 +12,6 @@ on:
workflow_dispatch:


# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
Expand All @@ -47,8 +36,8 @@ jobs:
- name: "Setup Python, Poetry and Dependencies"
uses: packetcoders/action-setup-cache-python-poetry@main
with:
python-version: 3.8
poetry-version: 1.2.2
python-version: 3.9
poetry-version: 1.8.3

- name: Install notebook dependencies
run: poetry install -E notebook --with docs
Expand All @@ -64,13 +53,6 @@ jobs:
cp -r $GITHUB_WORKSPACE/tutorial $GITHUB_WORKSPACE/docs/
cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
# To be included later
# - name: Cache docs build
# id: cache-docs
# uses: actions/cache@v3
# with:
# path: $GITHUB_WORKSPACE/_build
# key: ${{ runner.os }}-docs
- name: download RAW data
# if: steps.cache-primes.outputs.cache-hit != 'true'
Expand All @@ -84,25 +66,88 @@ jobs:
poetry run python scripts/build_flash_parquets.py
poetry run python scripts/build_sxp_parquets.py
# to be removed later. This theme doesn't support <3.9 python and our lock file contains 3.8
- name: install pydata-sphinx-theme
run: |
poetry run pip install pydata-sphinx-theme
- name: Change version for develop build
if: startsWith(github.ref, 'refs/heads/') && github.ref != 'refs/heads/main'
run: |
VERSION=`sed -n 's/^version = "\(.*\)".*/\1/p' $GITHUB_WORKSPACE/pyproject.toml`
MOD_VERSION=$VERSION".dev0"
echo $MOD_VERSION
sed -i "s/^version = \"$VERSION\"/version = \"$MOD_VERSION\"/" $GITHUB_WORKSPACE/pyproject.toml
- name: build Sphinx docs
run: poetry run sphinx-build -b html $GITHUB_WORKSPACE/docs $GITHUB_WORKSPACE/_build

- name: Setup Pages
uses: actions/configure-pages@v4

- name: Upload artifact
uses: actions/upload-pages-artifact@v3
uses: actions/upload-artifact@v4
with:
path: '_build'
name: sphinx-docs
path: _build

# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
# this job pushes the built documentation to the docs repository
push:
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
- name: Checkout docs repo
uses: actions/checkout@v2
with:
repository: ${{ github.repository_owner }}/docs
token: ${{ secrets.GITHUB_TOKEN }}
path: 'docs-repo'

- name: Set up Python 3.9
uses: actions/setup-python@v4
with:
python-version: 3.9

- name: Setup SSH
uses: webfactory/[email protected]
with:
ssh-private-key: ${{ secrets.SSH_DOCS_DEPLOY_KEY }}

- name: Download artifact
uses: actions/download-artifact@v4
with:
name: sphinx-docs
path: sphinx-docs

- name: Determine version folder
id: version-folder
run: |
if [[ $GITHUB_REF == refs/tags/* ]]; then
VERSION=${GITHUB_REF#refs/tags/}
echo "folder=sed/$VERSION" >> $GITHUB_OUTPUT
rm docs-repo/sed/stable
ln -s -r docs-repo/sed/$VERSION docs-repo/sed/stable
elif [[ $GITHUB_REF == refs/heads/main ]]; then
echo "folder=sed/latest" >> $GITHUB_OUTPUT
else
echo "folder=sed/develop" >> $GITHUB_OUTPUT
fi
- name: Update switcher.json
run: |
VERSION=`grep "<title>SED documentation." sphinx-docs/index.html | sed -n 's/.*SED \(.*\) documentation.*/\1/p'`
echo "python docs-repo/sed/update_switcher.py docs-repo/sed/switcher.json $GITHUB_REF $VERSION"
python docs-repo/sed/update_switcher.py docs-repo/sed/switcher.json $GITHUB_REF $VERSION
- name: Copy documentation to the right version folder
run: |
mkdir -p docs-repo/${{ steps.version-folder.outputs.folder }}
cp -r sphinx-docs/* docs-repo/${{ steps.version-folder.outputs.folder }}
rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/.doctrees
rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/tutorial/*.ipynb
- name: Push changes
run: |
cd docs-repo
git config user.name github-actions
git config user.email [email protected]
git add .
git commit -m "Update documentation"
git push
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
*.hdf5
*.nxs
*.nx
*.nxs
*.parquet
*.zip
**/datasets/*
**/processed/*
Expand Down
100 changes: 26 additions & 74 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[![Documentation Status](https://github.com/OpenCOMPES/sed/actions/workflows/documentation.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://opencompes.github.io/docs/sed/latest/))
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
![](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)
Expand All @@ -7,23 +7,21 @@
[![](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)

Backend to handle photoelectron resolved datastreams.
**sed-processor** is a backend to process and bin multidimensional single-event datastreams, with the intended primary use case in multidimensional photoelectron spectroscopy using time-of-flight instruments.

# Table of Contents
[Installation](#installation)
- [For Users (pip)](#for-users-pip)
- [For Contributors (pip)](#for-contributors-pip)
- [For Maintainers (poetry)](#for-maintainers-poetry)
It builds on [Dask](https://www.dask.org/) dataframes, where each column represents a multidimensional "coordinate" such as position, time-of-flight, pump-probe delay etc., and each entry represents one electron. The `SedProcessor` class provides a single user entry point, and provides functions for handling various workflows for coordinate transformation, e.g. corrections and calibrations.

# Installation
Furthermore, "sed-processor" provides fast and parallelized binning routines to compute multidimensional histograms from the processed dataframes in a delayed fashion, thus reducing requirements on cpu power and memory consumption.

Finally, in contains several export routines, including export into the [NeXus](https://www.nexusformat.org/) format with rich and standardized metadata annotation.

## For Users (pip)
# Installation

### Prerequisites
## Prerequisites
- Python 3.8+
- pip

### Steps
## Steps
- Create a new virtual environment using either venv, pyenv, conda, etc. See below for an example.

```bash
Expand Down Expand Up @@ -58,75 +56,29 @@ python -m ipykernel install --user --name=sed_kernel
pip install sed-processor
```

## For Contributors (pip)

### Prerequisites
- Git
- Python 3.8+
- pip

### Steps
1. Clone the repository:

```bash
git clone https://github.com/OpenCOMPES/sed.git
cd sed
```

2. Create and activate a virtual environment:

```bash
# Create a virtual environment
python -m venv .sed-dev
# Documentation
Comprehensive documentation including several workflow examples can be found here:
https://opencompes.github.io/docs/sed/latest/

# Activate the virtual environment
# On macOS/Linux
source .sed-dev/bin/activate

# On Windows
.sed-dev\Scripts\activate
```
# Contributing
Users are welcome to contribute to the development of **sed-processor**. Information how to contribute, including how to install developer versions can be found in the [documentation](https://opencompes.github.io/docs/sed/latest/misc/contribution.html)

3. Install the repository in editable mode with all dependencies:

```bash
pip install -e .[all]
```

Now you have the development version of `sed` installed in your local environment. Feel free to make changes and submit pull requests.

## For Maintainers (poetry)

### Prerequisites
- Poetry: [Poetry Installation](https://python-poetry.org/docs/#installation)

### Steps
- Create a virtual environment by typing:

```bash
poetry shell
```

- A new shell will be spawned with the new environment activated.

- Install the dependencies from the `pyproject.toml` by typing:

```bash
poetry install --with dev, docs
```
We would like to thank our contributors!

- 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.
[![Contributors](https://contrib.rocks/image?repo=OpenCOMPES/sed)](https://github.com/OpenCOMPES/sed/graphs/contributors)

- Install the optional dependencies:

```bash
poetry install -E notebook
```
## License

- Make sure to run the command below within your virtual environment (`poetry run` ensures this) by typing:
sed-processor is licenced under the MIT license

```bash
poetry run ipython kernel install --user --name=sed_poetry
```
Copyright (c) 2022-2024 OpenCOMPES

- The new kernel will now be available in your Jupyter kernels list.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
30 changes: 27 additions & 3 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,9 @@ def _get_project_meta():
return tomlkit.parse(file_contents)["tool"]["poetry"]


# -- Project information -----------------------------------------------------
pkg_meta = _get_project_meta()
project = str(pkg_meta["name"])
project = "SED"
copyright = "2024, OpenCOMPES team"
author = "OpenCOMPES team"

Expand All @@ -41,12 +42,12 @@ def _get_project_meta():
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx_rtd_theme",
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.autosummary",
"sphinx.ext.viewcode",
"sphinx.ext.coverage",
"sphinx_autodoc_typehints",
"bokeh.sphinxext.bokeh_autodoc",
Expand All @@ -56,6 +57,8 @@ def _get_project_meta():
]


exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]

autoclass_content = "class"
autodoc_member_order = "bysource"

Expand Down Expand Up @@ -98,7 +101,28 @@ def _get_project_meta():
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_rtd_theme"
html_theme = "pydata_sphinx_theme"

html_theme_options = {
"github_url": "https://github.com/OpenCOMPES/sed",
"primary_sidebar_end": ["indices.html"],
"navbar_center": ["version-switcher", "navbar-nav"],
"show_nav_level": 2,
"show_version_warning_banner": True,
# maybe better to use _static/switcher.json on github pages link instead of the following
"switcher": {
"json_url": "https://raw.githubusercontent.com/OpenCOMPES/docs/main/sed/switcher.json",
"version_match": version,
},
"content_footer_items": ["last-updated"],
}

html_context = {
"github_user": "OpenCOMPES",
"github_repo": "sed",
"github_version": "main",
"doc_path": "docs",
}

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
Expand Down
2 changes: 0 additions & 2 deletions docs/getting_started.rst

This file was deleted.

Loading

0 comments on commit 439844b

Please sign in to comment.