Skip to content

Commit 25e7bac

Browse files
zain-sohailzain-sohail
authored
Merge pull request #474 from OpenCOMPES/pydata-docs-theme-main
Docs website change: Pydata docs theme
2 parents b51da2e + f68c204 commit 25e7bac

24 files changed

+423
-258
lines changed

‎.cspell/custom-dictionary.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,7 @@ ptargs
286286
pullrequest
287287
pval
288288
pyarrow
289+
pydata
289290
pyenv
290291
pygments
291292
pynxtools
@@ -370,6 +371,7 @@ utime
370371
varnames
371372
venv
372373
verts
374+
viewcode
373375
vmax
374376
voxels
375377
VTOF

‎.github/workflows/documentation.yml

Lines changed: 79 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ on:
33
# Triggers the workflow on push but only for the main branch
44
push:
55
branches: [ main ]
6+
tags: [ v* ]
67
paths:
78
- sed/**/*
89
- tutorial/**
@@ -11,18 +12,6 @@ on:
1112
workflow_dispatch:
1213

1314

14-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
15-
permissions:
16-
contents: read
17-
pages: write
18-
id-token: write
19-
20-
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
21-
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
22-
concurrency:
23-
group: "pages"
24-
cancel-in-progress: false
25-
2615
jobs:
2716
build:
2817
runs-on: ubuntu-latest
@@ -47,8 +36,8 @@ jobs:
4736
- name: "Setup Python, Poetry and Dependencies"
4837
uses: packetcoders/action-setup-cache-python-poetry@main
4938
with:
50-
python-version: 3.8
51-
poetry-version: 1.2.2
39+
python-version: 3.9
40+
poetry-version: 1.8.3
5241

5342
- name: Install notebook dependencies
5443
run: poetry install -E notebook --with docs
@@ -65,13 +54,6 @@ jobs:
6554
cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
6655
rm $GITHUB_WORKSPACE/docs/tutorial/5_sxp_workflow.ipynb
6756
68-
# To be included later
69-
# - name: Cache docs build
70-
# id: cache-docs
71-
# uses: actions/cache@v3
72-
# with:
73-
# path: $GITHUB_WORKSPACE/_build
74-
# key: ${{ runner.os }}-docs
7557
7658
- name: download RAW data
7759
# if: steps.cache-primes.outputs.cache-hit != 'true'
@@ -84,25 +66,88 @@ jobs:
8466
cd $GITHUB_WORKSPACE/docs
8567
poetry run python scripts/build_flash_parquets.py
8668
69+
# to be removed later. This theme doesn't support <3.9 python and our lock file contains 3.8
70+
- name: install pydata-sphinx-theme
71+
run: |
72+
poetry run pip install pydata-sphinx-theme
73+
74+
- name: Change version for develop build
75+
if: startsWith(github.ref, 'refs/heads/') && github.ref != 'refs/heads/main'
76+
run: |
77+
VERSION=`sed -n 's/^version = "\(.*\)".*/\1/p' $GITHUB_WORKSPACE/pyproject.toml`
78+
MOD_VERSION=$VERSION".dev0"
79+
echo $MOD_VERSION
80+
sed -i "s/^version = \"$VERSION\"/version = \"$MOD_VERSION\"/" $GITHUB_WORKSPACE/pyproject.toml
81+
8782
- name: build Sphinx docs
8883
run: poetry run sphinx-build -b html $GITHUB_WORKSPACE/docs $GITHUB_WORKSPACE/_build
8984

90-
- name: Setup Pages
91-
uses: actions/configure-pages@v4
92-
9385
- name: Upload artifact
94-
uses: actions/upload-pages-artifact@v3
86+
uses: actions/upload-artifact@v4
9587
with:
96-
path: '_build'
88+
name: sphinx-docs
89+
path: _build
9790

98-
# Deployment job
99-
deploy:
100-
environment:
101-
name: github-pages
102-
url: ${{ steps.deployment.outputs.page_url }}
91+
# this job pushes the built documentation to the docs repository
92+
push:
10393
runs-on: ubuntu-latest
10494
needs: build
10595
steps:
106-
- name: Deploy to GitHub Pages
107-
id: deployment
108-
uses: actions/deploy-pages@v4
96+
- name: Checkout docs repo
97+
uses: actions/checkout@v2
98+
with:
99+
repository: ${{ github.repository_owner }}/docs
100+
token: ${{ secrets.GITHUB_TOKEN }}
101+
path: 'docs-repo'
102+
103+
- name: Set up Python 3.9
104+
uses: actions/setup-python@v4
105+
with:
106+
python-version: 3.9
107+
108+
- name: Setup SSH
109+
uses: webfactory/[email protected]
110+
with:
111+
ssh-private-key: ${{ secrets.SSH_DOCS_DEPLOY_KEY }}
112+
113+
- name: Download artifact
114+
uses: actions/download-artifact@v4
115+
with:
116+
name: sphinx-docs
117+
path: sphinx-docs
118+
119+
- name: Determine version folder
120+
id: version-folder
121+
run: |
122+
if [[ $GITHUB_REF == refs/tags/* ]]; then
123+
VERSION=${GITHUB_REF#refs/tags/}
124+
echo "folder=sed/$VERSION" >> $GITHUB_OUTPUT
125+
rm docs-repo/sed/stable
126+
ln -s -r docs-repo/sed/$VERSION docs-repo/sed/stable
127+
elif [[ $GITHUB_REF == refs/heads/main ]]; then
128+
echo "folder=sed/latest" >> $GITHUB_OUTPUT
129+
else
130+
echo "folder=sed/develop" >> $GITHUB_OUTPUT
131+
fi
132+
133+
- name: Update switcher.json
134+
run: |
135+
VERSION=`grep "<title>SED documentation." sphinx-docs/index.html | sed -n 's/.*SED \(.*\) documentation.*/\1/p'`
136+
echo "python docs-repo/sed/update_switcher.py docs-repo/sed/switcher.json $GITHUB_REF $VERSION"
137+
python docs-repo/sed/update_switcher.py docs-repo/sed/switcher.json $GITHUB_REF $VERSION
138+
139+
- name: Copy documentation to the right version folder
140+
run: |
141+
mkdir -p docs-repo/${{ steps.version-folder.outputs.folder }}
142+
cp -r sphinx-docs/* docs-repo/${{ steps.version-folder.outputs.folder }}
143+
rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/.doctrees
144+
rm -rf docs-repo/${{ steps.version-folder.outputs.folder }}/tutorial/*.ipynb
145+
146+
- name: Push changes
147+
run: |
148+
cd docs-repo
149+
git config user.name github-actions
150+
git config user.email [email protected]
151+
git add .
152+
git commit -m "Update documentation"
153+
git push

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
*.hdf5
66
*.nxs
77
*.nx
8-
*.nxs
8+
*.parquet
99
*.zip
1010
**/datasets/*
1111
**/processed/*

‎README.md

Lines changed: 25 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,21 @@
77
[![](https://img.shields.io/pypi/v/sed-processor)](https://pypi.org/project/sed-processor)
88
[![Coverage Status](https://coveralls.io/repos/github/OpenCOMPES/sed/badge.svg?branch=main&kill_cache=1)](https://coveralls.io/github/OpenCOMPES/sed?branch=main)
99

10-
Backend to handle photoelectron resolved datastreams.
10+
**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.
1111

12-
# Table of Contents
13-
[Installation](#installation)
14-
- [For Users (pip)](#for-users-pip)
15-
- [For Contributors (pip)](#for-contributors-pip)
16-
- [For Maintainers (poetry)](#for-maintainers-poetry)
12+
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.
1713

18-
# Installation
14+
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.
15+
16+
Finally, in contains several export routines, including export into the [NeXus](https://www.nexusformat.org/) format with rich and standardized metadata annotation.
1917

20-
## For Users (pip)
18+
# Installation
2119

22-
### Prerequisites
20+
## Prerequisites
2321
- Python 3.8+
2422
- pip
2523

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

2927
```bash
@@ -58,75 +56,29 @@ python -m ipykernel install --user --name=sed_kernel
5856
pip install sed-processor
5957
```
6058

61-
## For Contributors (pip)
62-
63-
### Prerequisites
64-
- Git
65-
- Python 3.8+
66-
- pip
67-
68-
### Steps
69-
1. Clone the repository:
70-
71-
```bash
72-
git clone https://github.com/OpenCOMPES/sed.git
73-
cd sed
74-
```
75-
76-
2. Create and activate a virtual environment:
77-
78-
```bash
79-
# Create a virtual environment
80-
python -m venv .sed-dev
59+
# Documentation
60+
Comprehensive documentation including several workflow examples can be found here:
61+
https://opencompes.github.io/docs/sed/latest/
8162

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

86-
# On Windows
87-
.sed-dev\Scripts\activate
88-
```
64+
# Contributing
65+
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)
8966

90-
3. Install the repository in editable mode with all dependencies:
91-
92-
```bash
93-
pip install -e .[all]
94-
```
95-
96-
Now you have the development version of `sed` installed in your local environment. Feel free to make changes and submit pull requests.
97-
98-
## For Maintainers (poetry)
99-
100-
### Prerequisites
101-
- Poetry: [Poetry Installation](https://python-poetry.org/docs/#installation)
102-
103-
### Steps
104-
- Create a virtual environment by typing:
105-
106-
```bash
107-
poetry shell
108-
```
109-
110-
- A new shell will be spawned with the new environment activated.
111-
112-
- Install the dependencies from the `pyproject.toml` by typing:
113-
114-
```bash
115-
poetry install --with dev, docs
116-
```
67+
We would like to thank our contributors!
11768

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

120-
- Install the optional dependencies:
12171

122-
```bash
123-
poetry install -E notebook
124-
```
72+
## License
12573

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

128-
```bash
129-
poetry run ipython kernel install --user --name=sed_poetry
130-
```
76+
Copyright (c) 2022-2024 OpenCOMPES
13177

132-
- The new kernel will now be available in your Jupyter kernels list.
78+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
79+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
80+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
81+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
82+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
83+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
84+
SOFTWARE.

‎docs/conf.py

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,9 @@ def _get_project_meta():
2525
return tomlkit.parse(file_contents)["tool"]["poetry"]
2626

2727

28+
# -- Project information -----------------------------------------------------
2829
pkg_meta = _get_project_meta()
29-
project = str(pkg_meta["name"])
30+
project = "SED"
3031
copyright = "2024, OpenCOMPES team"
3132
author = "OpenCOMPES team"
3233

@@ -41,12 +42,12 @@ def _get_project_meta():
4142
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4243
# ones.
4344
extensions = [
44-
"sphinx_rtd_theme",
4545
"sphinx.ext.autodoc",
4646
"sphinx.ext.napoleon",
4747
"sphinx.ext.todo",
4848
"sphinx.ext.coverage",
4949
"sphinx.ext.autosummary",
50+
"sphinx.ext.viewcode",
5051
"sphinx.ext.coverage",
5152
"sphinx_autodoc_typehints",
5253
"bokeh.sphinxext.bokeh_autodoc",
@@ -56,6 +57,8 @@ def _get_project_meta():
5657
]
5758

5859

60+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
61+
5962
autoclass_content = "class"
6063
autodoc_member_order = "bysource"
6164

@@ -98,7 +101,28 @@ def _get_project_meta():
98101
# The theme to use for HTML and HTML Help pages. See the documentation for
99102
# a list of builtin themes.
100103
#
101-
html_theme = "sphinx_rtd_theme"
104+
html_theme = "pydata_sphinx_theme"
105+
106+
html_theme_options = {
107+
"github_url": "https://github.com/OpenCOMPES/sed",
108+
"primary_sidebar_end": ["indices.html"],
109+
"navbar_center": ["version-switcher", "navbar-nav"],
110+
"show_nav_level": 2,
111+
"show_version_warning_banner": True,
112+
# maybe better to use _static/switcher.json on github pages link instead of the following
113+
"switcher": {
114+
"json_url": "https://github.com/raw/OpenCOMPES/docs/main/sed/switcher.json",
115+
"version_match": version,
116+
},
117+
"content_footer_items": ["last-updated"],
118+
}
119+
120+
html_context = {
121+
"github_user": "OpenCOMPES",
122+
"github_repo": "sed",
123+
"github_version": "main",
124+
"doc_path": "docs",
125+
}
102126

103127
# Add any paths that contain custom static files (such as style sheets) here,
104128
# relative to this directory. They are copied after the builtin static files,

‎docs/getting_started.rst

Lines changed: 0 additions & 2 deletions
This file was deleted.

0 commit comments

Comments
 (0)