easydiffraction 0.5.5__tar.gz → 0.5.6__tar.gz

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/.github/workflows/build-docs.yml

@@ -5,6 +5,9 @@ on:
   push:
     # Selected branches
     branches: [develop, master, docs, patch]
+    # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
+    tags:
+      - 'v*'
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -33,18 +36,22 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      # Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml
-      - name: Get GitHub repository
-        run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> $GITHUB_ENV
+      - name: Check-out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history + tags. needed to get the latest release version
 
       # 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
+      - name: Set RELEASE_VERSION env variable (latest easydiffraction release)
         run: |
-          git clone --depth 1 https://github.com/easyscience/${{ github.event.repository.name }} .
-          git fetch --tags
-          echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV
+          git fetch --tags --force
+          echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> "$GITHUB_ENV"
+
+      # Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml
+      - name: Set GITHUB_REPOSITORY env variable
+        run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> "$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
@@ -57,9 +64,6 @@ jobs:
       #    dark-mode on
       #    dark-mode status
 
-      - name: Check-out repository
-        uses: actions/checkout@v4
-
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
@@ -113,7 +117,7 @@ jobs:
           cp -R ${{ env.NOTEBOOKS_DIR }}/data docs/${{ env.NOTEBOOKS_DIR }}/
           jupytext ${{ env.NOTEBOOKS_DIR }}/*.py --from py:percent --to ipynb
           nbstripout ${{ env.NOTEBOOKS_DIR }}/*.ipynb
-          python tools/nb_uncomment_pip.py ${{ env.NOTEBOOKS_DIR }}/
+          python tools/prepare_notebooks.py ${{ env.NOTEBOOKS_DIR }}/
           mv ${{ env.NOTEBOOKS_DIR }}/*.ipynb docs/${{ env.NOTEBOOKS_DIR }}/
 
       # The following step is needed to avoid the following message during the build:
@@ -159,10 +163,10 @@ jobs:
           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 'gh_pages'
-      - name: Upload built site as artifact for gh_pages (master branch)
-        if: ${{ env.CI_BRANCH == 'master' }}
+      # This artifact is only uploaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
+      # and is used to push content to gh_pages for custom domain deployment.
+      - name: Upload built site as artifact for gh_pages (tagged release)
+        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/upload-artifact@v4
         with:
           name: artifact # name of the artifact (without the extension zip)
@@ -205,26 +209,30 @@ jobs:
           (all branches)
         uses: actions/deploy-pages@v4
 
-      # Download built site as artifact from a previous job for gh_pages (master branch)
-      - name: Download built site from previous job (master branch)
-        if: ${{ env.CI_BRANCH == 'master' }}
+      # Download built site as artifact from a previous job for gh_pages (tagged release)
+      # This artifact is only downloaded on tagged releases (tags starting with 'v', e.g., v1.0.3)
+      # and is used to push content to gh_pages for custom domain deployment.
+      - name: Download built site from previous job (tagged release)
+        if: startsWith(github.ref, 'refs/tags/v')
         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
+      # This push happens only for tagged releases (tags starting with 'v'),
+      # which triggers deployment to the custom domain via webhook.
+      #
       # 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.
-      # Deploying is done with a webhook:
+      # Then the gh_pages branch is used to deploy the site to the custom domain.
+      # Deploying is done with a webhook added via:
       # 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 custom domain
-          (master branch)
-        if: ${{ env.CI_BRANCH == 'master' }}
+          (tagged release)
+        if: startsWith(github.ref, 'refs/tags/v')
         uses: s0/git-publish-subdir-action@develop
         env:
           GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }}

easydiffraction-0.5.6/.github/workflows/draft-release-notes.yml

@@ -0,0 +1,27 @@
+# Drafts your next Release notes as pull requests are merged into
+# default branch
+
+name: Update release draft
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  draft-release-notes:
+    permissions:
+      # write permission is required to create a github release
+      contents: write
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Drafts the next Release notes
+        uses: release-drafter/release-drafter@v6
+        with:
+          disable-autolabeler: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/.github/workflows/test-tutorials.yaml

@@ -151,7 +151,7 @@ jobs:
         run: |
           jupytext ${{ env.NOTEBOOKS_DIR }}/*.py --from py:percent --to ipynb
           nbstripout ${{ env.NOTEBOOKS_DIR }}/*.ipynb
-          python tools/nb_uncomment_pip.py ${{ env.NOTEBOOKS_DIR }}/
+          python tools/prepare_notebooks.py ${{ env.NOTEBOOKS_DIR }}/
 
       - name: Run tutorials as Jupyter Notebooks (using src/ as the source dir)
         shell: bash

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/DEVELOPMENT.md

@@ -106,22 +106,31 @@ This is an example of a workflow that describes the development process.
   ```
 - Add extra files to build documentation (from `../assets-docs/` and
   `../assets-branding/` directories)
+
   ```bash
   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_dark.svg docs/assets/images/
-  cp ../assets-branding/EasyDiffraction/logos/ed-logo_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
+  cp ../assets-branding/easydiffraction/hero/dark.png docs/assets/images/hero_dark.png
+  cp ../assets-branding/easydiffraction/hero/light.png docs/assets/images/hero_light.png
+  cp ../assets-branding/easydiffraction/logos/dark.svg docs/assets/images/logo_dark.svg
+  cp ../assets-branding/easydiffraction/logos/light.svg docs/assets/images/logo_light.svg
+  cp ../assets-branding/easydiffraction/icons/color.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/EasyScienceOrg/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg
-  cp -R examples/ docs/examples/
-  cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml
+  cp ../assets-branding/easydiffraction/icons/bw.svg overrides/.icons/easydiffraction.svg
+  cp ../assets-branding/easyscience-org/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg
+
+  jupytext tutorials/*.py --from py:percent --to ipynb
+  nbstripout tutorials/*.ipynb
+  cp tutorials/*.ipynb docs/tutorials/
+  cp -R tutorials/data docs/tutorials/
+
+  python tools/create_mkdocs-yml.py
   ```
+
 - Build documentation with MkDocs - static site generator
   ```bash
   export JUPYTER_PLATFORM_DIRS=1

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easydiffraction
-Version: 0.5.5
+Version: 0.5.6
 Summary: Diffraction data analysis
 Project-URL: homepage, https://easydiffraction.org
 Project-URL: documentation, https://docs.easydiffraction.org/lib

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/docs/introduction/index.md

@@ -49,7 +49,7 @@ Zenodo, each with a version-specific Digital Object Identifier (DOI).
 Citation details in various styles (e.g., APA, MLA) and formats (e.g., BibTeX,
 JSON)  
 are available on the
-[Zenodo archive page](https://doi.org/10.5281/zenodo.16806522).
+[Zenodo archive page](https://doi.org/10.5281/zenodo.16806521).
 
 ## Contributing
 

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/src/easydiffraction/plotting/plotters/plotter_plotly.py

@@ -12,7 +12,7 @@ except ImportError:
     display = None
     HTML = None
 
-from easydiffraction.utils.utils import is_pycharm
+from easydiffraction.utils.utils import is_github_ci
 
 from .plotter_base import SERIES_CONFIG
 from .plotter_base import PlotterBase
@@ -106,14 +106,13 @@ class PlotlyPlotter(PlotterBase):
 
         # Show the figure
 
-        # The standard `fig.show()` method method triggers the following
-        # warning during the DMSC Summer School 2025 book build process:
-        # WARNING: skipping unknown output mime type:
-        # application/vnd.plotly.v1+json [mystnb.unknown_mime_type]
-        # So, instead, we will use `pio.to_html()` to convert the figure
-        # to HTML and keep `fig.show()` in PyCharm only.
-
-        if is_pycharm() or display is None or HTML is None:
+        # In GitHub CI builds (e.g., during Jupyter Book generation), avoid
+        #
+        # calling `fig.show()`
+        # because it can emit `application/vnd.plotly.v1+json` outputs that some toolchains warn about.
+        # Instead, convert the figure to HTML and display it directly.
+        # Use a regular Figure and show it
+        if not is_github_ci() or display is None or HTML is None:
             fig.show(config=config)
         else:
             html_fig = pio.to_html(

{easydiffraction-0.5.5 → easydiffraction-0.5.6}/src/easydiffraction/utils/utils.py

@@ -101,6 +101,17 @@ def is_pycharm() -> bool:
     return os.environ.get('PYCHARM_HOSTED') == '1'
 
 
+def is_github_ci() -> bool:
+    """
+    Determines if the current process is running in GitHub Actions CI.
+
+    Returns:
+        bool: True if the environment variable ``GITHUB_ACTIONS`` is set
+        (Always "true" on GitHub Actions), False otherwise.
+    """
+    return os.environ.get('GITHUB_ACTIONS') is not None
+
+
 def render_table(
     columns_data,
     columns_alignment,

easydiffraction-0.5.6/tools/prepare_notebooks.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Uncomment `# !pip ...` and `# ed.download_from_repository ...` lines in Jupyter
+notebooks so they become `!pip ...` and `ed.download_from_repository ...` respectively.
+
+Additionally, adjust cell metadata and tags according to DMSC Summer School rules:
+- If a cell has the `dmsc-school-hint` or `solution` tag, add
+  `{"jupyter": {"source_hidden": true}}` so it is collapsed by default.
+- If a cell has the `remove-cell` tag, replace it with `hide_in_docs`.
+- If a cell has the `non-editable` tag, set `editable: false` in metadata.
+- Remove all tags except `hide_in_docs`.
+
+Notes:
+- Operates only on code cells for uncommenting (does not touch markdown sources),
+  but processes metadata/tags for ALL cells.
+- Matches lines that start with optional whitespace, then `# !pip`
+  (e.g., "  # !pip install ...").
+- Also matches lines that start with optional whitespace, then
+  `# ed.download_from_repository` (e.g., "  # ed.download_from_repository(...)").
+- Rewrites to keep the original indentation and replace the leading
+  "# !pip" with "!pip", and "# ed.download_from_repository" with "ed.download_from_repository".
+- Processes one or more paths (files or directories) given as CLI args,
+  recursively for directories.
+
+New CLI options:
+- `--remove-cell true|false` to control how cells tagged `remove-cell` are handled:
+  remove entirely (true) or map tag to `hide_in_docs` (false, default).
+- `--strip-solution true|false` to control handling of cells tagged `solution`:
+  replace content with placeholder (true) or collapse via source_hidden (false, default).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import nbformat
+from nbformat.validator import normalize
+
+# Regex: beginning-of-line, capture leading whitespace, then "#", spaces, then "!pip"
+_PIP_PATTERN = re.compile(r'^(\s*)#\s*!pip\b')
+# Regex: beginning-of-line, capture leading whitespace, then "#", spaces, then "ed.download_from_repository"
+_ED_PATTERN = re.compile(r'^(\s*)#\s*ed\.download_from_repository\b')
+
+
+def fix_cell_source(src: str) -> tuple[str, int]:
+    """
+    Replace lines starting with optional whitespace + '# !pip' with '!pip',
+    and lines starting with optional whitespace + '# ed.download_from_repository'
+    with 'ed.download_from_repository'.
+    Returns the updated source and number of replacements performed.
+    """
+    changed = 0
+    new_lines: list[str] = []
+    for line in src.splitlines(keepends=False):
+        orig_line = line
+        # Replace # !pip
+        if _PIP_PATTERN.match(line):
+            line = _PIP_PATTERN.sub(r'\1!pip', line, count=1)
+        # Replace # ed.download_from_repository
+        if _ED_PATTERN.match(line):
+            line = _ED_PATTERN.sub(r'\1ed.download_from_repository', line, count=1)
+        if line != orig_line:
+            changed += 1
+        new_lines.append(line)
+    return ('\n'.join(new_lines), changed)
+
+
+def fix_cell_metadata(cell, *, remove_cell: bool, strip_solution: bool) -> tuple[int, bool]:
+    """
+    Apply tag/metadata rules:
+      - 'dmsc-school-hint' or 'solution' -> jupyter.source_hidden = True (unless strip_solution is True)
+      - 'remove-cell' -> either remove cell (if remove_cell=True) or rename to 'hide_in_docs'
+      - 'non-editable' -> editable = False
+      - keep only 'hide_in_docs' tag, drop all others (unless cell removed)
+      - if strip_solution=True and 'solution' tag present, replace source with placeholder instead of collapsing
+    Returns (number of changes applied, remove_this_cell flag).
+    """
+    changed = 0
+    remove_flag = False
+    md = cell.metadata
+
+    # Normalize tags list
+    tags = list(md.get('tags', []))
+
+    # Check for remove-cell tag and remove_cell flag
+    if 'remove-cell' in tags:
+        if remove_cell:
+            # Mark cell for removal
+            remove_flag = True
+            # Count change if tags existed (since removal is a change)
+            if tags:
+                changed += 1
+            # Skip further processing for this cell
+            return changed, remove_flag
+        else:
+            # rename remove-cell -> hide_in_docs (without duplicating)
+            new_tags = []
+            seen_hide = 'hide_in_docs' in tags
+            for t in tags:
+                if t == 'remove-cell':
+                    if not seen_hide:
+                        new_tags.append('hide_in_docs')
+                        seen_hide = True
+                else:
+                    new_tags.append(t)
+            if new_tags != tags:
+                tags = new_tags
+                changed += 1
+
+    # Handle 'solution' tag with strip_solution flag
+    if strip_solution and ('solution' in tags):
+        if getattr(cell, 'source', None) != '# Insert your solution:':
+            cell.source = '# Insert your solution:'
+            changed += 1
+        # Do not add jupyter.source_hidden in this case
+    else:
+        # Add jupyter.source_hidden when hint or solution tag present
+        if ('dmsc-school-hint' in tags) or ('solution' in tags):
+            jup = md.get('jupyter', {})
+            if jup.get('source_hidden') is not True:
+                jup['source_hidden'] = True
+                md['jupyter'] = jup
+                changed += 1
+
+    # 3) add editable: false for non-editable tag
+    if 'non-editable' in tags:
+        if md.get('editable') is not False:
+            md['editable'] = False
+            changed += 1
+
+    # 4) keep only 'hide_in_docs' and drop empty tag arrays from metadata, unless removing cell
+    if not remove_flag:
+        keep = ['hide_in_docs'] if 'hide_in_docs' in tags else []
+
+        if keep:  # we want to keep only 'hide_in_docs'
+            if md.get('tags') != keep:
+                md['tags'] = keep
+                changed += 1
+        else:
+            # remove empty tags key if present
+            if 'tags' in md:
+                # count as change if previously non-empty
+                if md['tags']:
+                    changed += 1
+                md.pop('tags', None)
+
+    return changed, remove_flag
+
+
+def process_notebook(path: Path, *, remove_cell: bool, strip_solution: bool) -> int:
+    """
+    Process a single .ipynb file.
+    - Uncomment magic/commented lines in code cells.
+    - Adjust cell metadata/tags as per school rules.
+    Returns number of changes made.
+    """
+    nb = nbformat.read(path, as_version=4)
+    total_changes = 0
+    new_cells = []
+    for cell in nb.cells:
+        # Source-only changes for code cells
+        if cell.cell_type == 'code':
+            new_src, changes = fix_cell_source(cell.source or '')
+            if changes:
+                cell.source = new_src
+                total_changes += changes
+        # Metadata/tag changes for all cells
+        md_changes, remove_it = fix_cell_metadata(cell, remove_cell=remove_cell, strip_solution=strip_solution)
+        total_changes += md_changes
+        if not remove_it:
+            new_cells.append(cell)
+    nb.cells = new_cells
+
+    # Normalize/add missing IDs if needed, even when no source/metadata changes were made
+    need_normalize = any('id' not in cell for cell in nb.cells)
+    if total_changes or need_normalize:
+        normalize(nb)
+        nbformat.write(nb, path)
+    return total_changes + (1 if need_normalize and not total_changes else 0)
+
+
+def iter_notebooks(paths: list[Path]):
+    for p in paths:
+        if p.is_dir():
+            yield from (q for q in p.rglob('*.ipynb') if q.is_file())
+        elif p.is_file() and p.suffix == '.ipynb':
+            yield p
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(
+        description=(
+            "Uncomment '# !pip ...' and '# ed.download_from_repository ...' in code cells, "
+            "and adjust cell metadata/tags (collapse hints/solutions, map 'remove-cell' "
+            "to 'hide_in_docs' or remove cells, keep only 'hide_in_docs', and mark 'non-editable' cells as not editable)."
+        )
+    )
+    ap.add_argument('paths', nargs='+', help='Notebook files or directories to process')
+    ap.add_argument('--dry-run', action='store_true', help='Report changes without writing files')
+    ap.add_argument(
+        '--remove-cell',
+        dest='remove_cell',
+        type=lambda s: str(s).lower() == 'true',
+        default=False,
+        help='true: remove cells tagged "remove-cell"; false (default): map tag to hide_in_docs',
+    )
+    ap.add_argument(
+        '--strip-solution',
+        dest='strip_solution',
+        type=lambda s: str(s).lower() == 'true',
+        default=False,
+        help='true: replace content of cells tagged "solution" with placeholder; false (default): collapse via source_hidden',
+    )
+    args = ap.parse_args(argv)
+
+    targets = list(iter_notebooks([Path(p) for p in args.paths]))
+    if not targets:
+        print('No .ipynb files found.', file=sys.stderr)
+        return 1
+
+    total_files = 0
+    total_changes = 0
+    for nb_path in targets:
+        changes = 0
+        if args.dry_run:
+            nb = nbformat.read(nb_path, as_version=4)
+            for cell in nb.cells:
+                if cell.cell_type == 'code':
+                    _, c = fix_cell_source(cell.source or '')
+                    changes += c
+                md_c, remove_it = fix_cell_metadata(cell, remove_cell=args.remove_cell, strip_solution=args.strip_solution)
+                changes += md_c
+                if remove_it:
+                    changes += 1  # count removal as a change
+        else:
+            changes = process_notebook(nb_path, remove_cell=args.remove_cell, strip_solution=args.strip_solution)
+
+        if changes:
+            action = 'WOULD UPDATE' if args.dry_run else 'UPDATED'
+            print(f'{action}: {nb_path} ({changes} change(s))')
+            total_files += 1
+            total_changes += changes
+
+    if total_files == 0:
+        print('No changes needed.')
+    else:
+        print(f'Done. Files changed: {total_files}, total changes: {total_changes}')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main(sys.argv[1:]))