Skip to content

backmerge after hotfix #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

backmerge after hotfix #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
104392b
Release 0.4.0 (#174)
rozyczko Apr 4, 2025
daff336
Added missing conversion field (#177)
rozyczko Jun 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 219 additions & 0 deletions .github/workflows/build-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
name: Build and deploy docs

on:
# Triggers the workflow on tag creation
push:
tags:
- 'v*'

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

env:
# Set the environment variables to be used in all jobs defined in this workflow
# Set the CI_BRANCH environment variable to be the branch name
# NOTE: Use the same branch name as the one of easyscience/diffraction-lib. This is
# required to download the Jupyter notebooks from the easyscience/diffraction-lib repository
# Set the NOTEBOOKS_DIR environment variable to be the directory containing the Jupyter notebooks
CI_BRANCH: ${{ github.head_ref || github.ref_name }}
NOTEBOOKS_DIR: examples

jobs:
# Job 1: Build the static files for the documentation site
build-docs:
runs-on: macos-14 # Use macOS to switch to dark mode for Plotly charts

steps:
- name: Cancel previous workflow runs
uses: n1hility/cancel-previous-runs@v2
with:
token: ${{ secrets.GITHUB_TOKEN }}

# Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml
- name: Get GitHub repository
run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> $GITHUB_ENV

# Save the latest release version of easyscience/diffraction-lib to RELEASE_VERSION
# RELEASE_VERSION is used in the mkdocs.yml file to set release_version.
# The release_version is then needed to display the latest release version in the index.md file
- name: Get the latest release version of EasyDiffraction Library
# This method is not working in CI with the following error: "API rate limit exceeded..."
#run: echo "RELEASE_VERSION=$(curl https://api.github.com/repos/easyscience/diffraction-lib/releases/latest | grep -i 'tag_name' | awk -F '"' '{print $4}')" >> $GITHUB_ENV
# This method is not optimal and takes some more time to run, but it works and it is reliable
run: |
git clone --depth 1 https://github.com/easyscience/EasyDiffractionLib .
git fetch --tags
echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV

# Activate dark mode to create documentation with Plotly charts in dark mode
# Need a better solution to automatically switch the chart colour theme based on the mkdocs material switcher
# Something similar to mkdocs_plotly_plugin https://haoda-li.github.io/mkdocs-plotly-plugin/,
# but for generating documentation from notepads
- name: Activate dark mode
run: |
brew install dark-mode
dark-mode status
dark-mode on
dark-mode status

- name: Check-out repository
uses: actions/checkout@v4

- name: Set up Python environment
uses: actions/setup-python@v4
with:
python-version: '3.12'

- name: Upgrade package installer for Python
run: python -m pip install --upgrade pip

# Install MkDocs -- static site generator
# https://www.mkdocs.org
- name: Install MkDocs and its dependencies
run: >
pip install mkdocs mkdocs-material 'mkdocs-autorefs<1.3.0'
mkdocs-jupyter mkdocs-plugin-inline-svg
mkdocs-markdownextradata-plugin mkdocstrings-python

# Install EasyDiffraction Library to run Jupyter notebooks
# Install with the 'charts' and 'docs' extras
- name: Install EasyDiffraction Library and its dependencies
run: pip install 'easydiffraction[charts]'

# Download and add the extra files from the easyscience/assets-docs repository
- name: Get easyscience/assets-docs files
run: |
git clone https://github.com/easyscience/assets-docs.git
cp -R assets-docs/docs/assets/ docs/assets/
cp -R assets-docs/includes/ includes/
cp -R assets-docs/overrides/ overrides/

# Download and add the extra files from the easyscience/assets-branding repository
- name: Get easyscience/assets-branding files
run: |
git clone https://github.com/easyscience/assets-branding.git
mkdir -p docs/assets/images/
cp assets-branding/easydiffraction/logos/ed-logo-2_dark.svg docs/assets/images/
cp assets-branding/easydiffraction/logos/ed-logo-2_light.svg docs/assets/images/
cp assets-branding/easydiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png
mkdir -p overrides/.icons/
cp assets-branding/easydiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg
cp assets-branding/easyscience-org/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg

# Copy Jupyter notebooks from the project to the docs folder
# The notebooks are used to generate the documentation
- name:
Copy Jupyter notebooks from ${{ env.NOTEBOOKS_DIR }}/ to docs/${{
env.NOTEBOOKS_DIR }}/
run: cp -R ${{ env.NOTEBOOKS_DIR }}/ docs/${{ env.NOTEBOOKS_DIR }}/

# The following step is needed to avoid the following message during the build:
# "Matplotlib is building the font cache; this may take a moment"
- name: Pre-build site step
run: python -c "import easydiffraction"

# Create the mkdocs.yml configuration file
# The file is created by merging two files:
# - assets-docs/mkdocs.yml - the common configuration (theme, plugins, etc.)
# - docs/mkdocs.yml - the project-specific configuration (project name, TOC, etc.)
- name: Create mkdocs.yml file
run: cat assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml

# Build the static files
# Input: docs/ directory containing the Markdown files
# Output: site/ directory containing the generated HTML files
- name: Build site with MkDocs
run: |
export JUPYTER_PLATFORM_DIRS=1
mkdocs build

# Set up the Pages action to configure the static files to be deployed
# NOTE: The repository must have GitHub Pages enabled and configured to build using GitHub Actions
# This can be done via https://github.com/easyscience/diffraction-lib/settings/pages
# Select: Build and deploy - Source - GitHub Actions
- name: Setup GitHub Pages
uses: actions/configure-pages@v5

# Upload the static files from the site/ directory to be used in the next job
# This artifact is named github-pages and is a single gzip archive containing a single tar file
# The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages
# Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things
- name:
Upload built site as artifact for
easyscience.github.io/diffraction-lib (all branches)
uses: actions/upload-pages-artifact@v3
with:
path: site/

# Upload the static files from the site/ directory to be used in the next job
# This extra step is needed to allow the download of the artifact in the next job
# for pushing its content to the branch named 'easydiffraction.org'
- name:
Upload built site as artifact for gh_pages and easydiffraction.org
(master branch)
if: ${{ env.CI_BRANCH == 'master' }}
uses: actions/upload-artifact@v4
with:
name: artifact # name of the artifact (without the extension zip)
path: site/
if-no-files-found: 'error'
compression-level: 0

# Job 2: Deploy the static files
deploy-docs:
Comment on lines +24 to +163

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}

Copilot Autofix

AI 5 months ago

To fix the issue, we need to add a permissions block to the build-docs job in the workflow file. This block should explicitly set the permissions required for the job, which in this case is likely limited to contents: read. This ensures that the GITHUB_TOKEN used in the job has only the minimal permissions necessary to complete the tasks.

The changes should be made in the .github/workflows/build-docs.yml file, specifically within the build-docs job definition. No additional imports, methods, or definitions are required.

Suggested changeset 1
.github/workflows/build-docs.yml

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -24,2 +24,4 @@
     runs-on: macos-14 # Use macOS to switch to dark mode for Plotly charts
+    permissions:
+      contents: read
 
EOF
@@ -24,2 +24,4 @@
runs-on: macos-14 # Use macOS to switch to dark mode for Plotly charts
permissions:
contents: read

Copilot is powered by AI and may make mistakes. Always verify output.
needs: build-docs # previous job 'build-docs' need to be finished first

# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
permissions:
contents: read
pages: write # to deploy to Pages
id-token: write # to verify the deployment, originates from an appropriate source

# 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

# Deploy to the github-pages environment
environment:
name: github-pages # Artifact name
url: ${{ steps.deployment.outputs.page_url }}

runs-on: ubuntu-latest

steps:
# Deploy the static files created in the previous job to GitHub Pages
# To allow the deployment of the static files to GitHub Pages, no
# restrictions on the branch name need to be set for desired branches on
# https://github.com/easyscience/diffraction-lib/settings/environments
# Currently, only develop and master branches are allowed to deploy to GitHub Pages
# Deployed pages are available at https://easyscience.github.io/diffraction-lib
- name: Deploy to easyscience.github.io/diffraction-lib (all branches)
uses: actions/deploy-pages@v4

# Download built site as artifact from a previous job for gh_pages and easydiffraction.org (master branch)
- name: Download built site from previous job (master branch)
if: ${{ env.CI_BRANCH == 'master' }}
uses: actions/download-artifact@v4
with: # name or path are taken from the upload step of the previous job
name: artifact
path: site/ # directory to extract downloaded zipped artifacts

# Push the site files created in the previous job to the gh_pages branch
# To be able to push to the gh_pages branch, the personal GitHub API access
# token GH_API_PERSONAL_ACCSESS_TOKEN must be set for this repository via
# https://github.com/easyscience/diffraction-lib/settings/secrets/actions
# This branch is used to deploy the site to the custom domain https://easydiffraction.org
# Deploying is done with a webhook: https://github.com/easyscience/diffraction-lib/settings/hooks
# This is done for the gh_pages branch when the site is tested with a step above
- name:
Deploy to gh_pages branch to trigger deployment to easydiffraction.org
(master branch)
if: ${{ env.CI_BRANCH == 'master' }}
uses: s0/git-publish-subdir-action@develop
env:
GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }}
REPO: self
BRANCH: gh_pages
FOLDER: site
63 changes: 56 additions & 7 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,22 +27,30 @@ This is an example of a workflow that describes the development process.
```console
python -m pip install --upgrade pip
```
- Install easydiffraction from root with `dev` extras for development
- Install easydiffraction from root with `dev` extras for development, `charts`
extras for Jupyter notebooks and `docs` extras for building documentation
```console
pip install '.[dev]'
pip install '.[dev,charts,docs]'
```
- Make changes in the code
```console
...
```
- Check the validity of pyproject.toml
```console
validate-pyproject pyproject.toml
```
- Run Ruff - Python linter and code formatter (configuration is in
pyproject.toml) Linting (overwriting files)
pyproject.toml)<br/> Linting (overwriting files)
```console
ruff check . --fix
```
Formatting (overwriting files)
```console
ruff format .
```
- Install and run Prettier - code formatter for markdown, YAML, TOML files
Formatting (overwriting files)
- Install and run Prettier - code formatter for Markdown, YAML, TOML, etc. files
(configuration in prettierrc.toml)<br/> Formatting (overwriting files)
```console
npm install prettier prettier-plugin-toml --save-dev --save-exact
npx prettier . --write --config=prettierrc.toml
Expand All @@ -51,7 +59,8 @@ This is an example of a workflow that describes the development process.
```console
pytest tests/ --color=yes -n auto
```
- Clear all Jupyter notebooks output
- Clear all Jupyter notebooks output (Only those that were changed!). Replace
`examples/*.ipynb` with the path to the notebook(s) you want to clear
```console
jupyter nbconvert --clear-output --inplace examples/*.ipynb
```
Expand All @@ -61,7 +70,47 @@ This is an example of a workflow that describes the development process.
```
- Run Jupyter notebooks as tests
```console
pytest --nbmake examples/*ipynb --nbmake-timeout=300 --color=yes -n=auto
pytest --nbmake examples/ --ignore-glob='examples/*emcee*' --nbmake-timeout=300 --color=yes -n=auto
```
- Add extra files to build documentation (from `../assets-docs/` and
`../assets-branding/` directories)
```console
cp -R ../assets-docs/docs/assets/ docs/assets/
cp -R ../assets-docs/includes/ includes/
cp -R ../assets-docs/overrides/ overrides/
mkdir -p docs/assets/images/
cp ../assets-branding/easydiffraction/logos/ed-logo-2_dark.svg docs/assets/images/
cp ../assets-branding/easydiffraction/logos/ed-logo-2_light.svg docs/assets/images/
<!-- cp ../assets-branding/easydiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg
cp ../assets-branding/easydiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg -->
cp ../assets-branding/easydiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png
mkdir -p overrides/.icons/
cp ../assets-branding/easydiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg
cp ../assets-branding/easyscience-org/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg
cp -R examples/ docs/examples/
cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml
```
- Build documentation with MkDocs - static site generator
```console
export JUPYTER_PLATFORM_DIRS=1
mkdocs serve
```
- Test the documentation locally (built in the `site/` directory). E.g., on
macOS, open the site in the default browser via the terminal
```console
open http://127.0.0.1:8000
```
- Clean up after building documentation
```console
rm -rf site/
rm -rf docs/assets/
rm -rf includes/
rm -rf overrides/
rm -rf docs/examples/
rm -rf node_modules/
rm mkdocs.yml
rm package-lock.json
rm package.json
```
- Commit changes
```console
Expand Down
3 changes: 2 additions & 1 deletion LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
BSD 3-Clause License

Copyright (c) 2024, EasyDiffractionLib contributors (https://github.com/EasyScience/EasyDiffractionLib)
Copyright (c) 2025, EasyDiffraction contributors
(https://github.com/EasyScience/EasyDiffractionLib)
All rights reserved.

Redistribution and use in source and binary forms, with or without
Expand Down
11 changes: 5 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
<p align='left'>
<p>
<picture>
<!-- light mode logo -->
<source media='(prefers-color-scheme: light)' srcset='https://raw.githubusercontent.com/EasyScience/BrandingResources/refs/heads/master/EasyDiffraction/logos/ed-logo_light.svg'>
<source media='(prefers-color-scheme: light)' srcset='https://raw.githubusercontent.com/easyscience/assets-branding/refs/heads/master/easydiffraction/logos/ed-logo-2_light.svg'>
<!-- dark mode logo -->
<source media='(prefers-color-scheme: dark)' srcset='https://raw.githubusercontent.com/EasyScience/BrandingResources/refs/heads/master/EasyDiffraction/logos/ed-logo_dark.svg'>
<source media='(prefers-color-scheme: dark)' srcset='https://raw.githubusercontent.com/easyscience/assets-branding/refs/heads/master/easydiffraction/logos/ed-logo-2_dark.svg'>
<!-- default logo == light mode logo -->
<img src='https://raw.githubusercontent.com/EasyScience/BrandingResources/refs/heads/master/EasyDiffraction/logos/ed-logo_light.svg' alt='EasyDiffraction'>
<img src='https://raw.githubusercontent.com/easyscience/assets-branding/refs/heads/master/easydiffraction/logos/ed-logo-2_light.svg' alt='EasyDiffraction'>
</picture>
</p>

Expand Down Expand Up @@ -34,8 +34,7 @@ We welcome contributions! Our vision is for **EasyDiffraction** to be a
community-driven, open-source project supported by a diverse group of
contributors.

The project is currently maintained by the [European Spallation Source (ESS)] in
Sweden.
The project is currently maintained by the [European Spallation Source (ESS)].

If you'd like to contribute, please refer to our [Contributing Guidelines] for
information about our code of conduct and instructions on submitting pull
Expand Down
Loading