Merge pull request #474 from OpenCOMPES/pydata-docs-theme-main

Docs website change: Pydata docs theme
OpenCOMPES · Nov 10, 2024 · 25e7bac · 25e7bac
2 parents b51da2e + f68c204
commit 25e7bac
Show file tree

Hide file tree

Showing 24 changed files with 423 additions and 258 deletions.
diff --git a/.cspell/custom-dictionary.txt b/.cspell/custom-dictionary.txt
@@ -286,6 +286,7 @@ ptargs
 pullrequest
 pval
 pyarrow
+pydata
 pyenv
 pygments
 pynxtools
@@ -370,6 +371,7 @@ utime
 varnames
 venv
 verts
+viewcode
 vmax
 voxels
 VTOF

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -3,6 +3,7 @@ on:
   # Triggers the workflow on push but only for the main branch
   push:
     branches: [ main ]
+    tags: [ v* ]
     paths:
       - sed/**/*
       - tutorial/**
@@ -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
@@ -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
@@ -65,13 +54,6 @@ jobs:
           cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
           rm $GITHUB_WORKSPACE/docs/tutorial/5_sxp_workflow.ipynb
 
-      # 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'
@@ -84,25 +66,88 @@ jobs:
           cd $GITHUB_WORKSPACE/docs
           poetry run python scripts/build_flash_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
diff --git a/.gitignore b/.gitignore
@@ -5,7 +5,7 @@
 *.hdf5
 *.nxs
 *.nx
-*.nxs
+*.parquet
 *.zip
 **/datasets/*
 **/processed/*

diff --git a/README.md b/README.md
@@ -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
@@ -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.
diff --git a/docs/conf.py b/docs/conf.py
@@ -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"
 
@@ -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",
@@ -56,6 +57,8 @@ def _get_project_meta():
 ]
 
 
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
 autoclass_content = "class"
 autodoc_member_order = "bysource"
 
@@ -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,

diff --git a/docs/getting_started.rst b/docs/getting_started.rst