Merge pull request #67 from easyscience/patch

Enhances Notebook Workflows, Plot Rendering, and Documentation Updates

Author: AndrewSazonov

.github/workflows/build-docs.yml

@@ -33,18 +33,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 +61,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 +114,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:

.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

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

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
 

src/easydiffraction/plotting/plotters/plotter_plotly.py

@@ -12,7 +12,7 @@
     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 @@ def plot(
 
         # 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(

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,