Backmerge: patch from master into develop #104
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # This workflow builds and deploys documentation for the project. | |
| # | |
| # Steps overview: | |
| # Job 1: build-docs | |
| # - Builds documentation (including running Jupyter notebooks to generate output cells). | |
| # - Uploads the built site as a Pages artifact. | |
| # Job 2: deploy-dev | |
| # - Deploys the built site to GitHub Pages for development (pushes to develop/master). | |
| # Job 3: deploy-prod | |
| # - Deploys the built site to gh-pages branch for production (release tags starting with v*). | |
| # - This triggers deployment to a custom domain via webhook. | |
| # | |
| # The action summary page will contain links to the built artifact for downloading | |
| # and inspecting, as well as links to both the development and production versions of | |
| # the deployed documentation site. | |
| name: Docs build and deployment | |
| on: | |
| # Trigger the workflow on pull request | |
| pull_request: | |
| # Selected branches | |
| branches: [master, main, develop] | |
| # Trigger the workflow on push | |
| push: | |
| # Selected branches | |
| branches: [master, main, develop] | |
| # 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: | |
| # Allow only one concurrent workflow, skipping runs queued between the run | |
| # in-progress and latest queued. And cancel in-progress runs. | |
| concurrency: | |
| group: | |
| ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: true | |
| # Set the environment variables to be used in all jobs defined in this workflow | |
| env: | |
| # CI_BRANCH - the branch name (used in mkdocs.yml) | |
| # For PRs: github.head_ref is the source branch | |
| # For pushes: github.ref_name is the branch | |
| # For tags: github.ref_name is the tag name | |
| # GITHUB_REPOSITORY - the repository name (used in mkdocs.yml) | |
| # NOTEBOOKS_DIR - the directory containing the Jupyter notebooks (used in mkdocs.yml) | |
| DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} | |
| DEVELOP_BRANCH: develop | |
| CI_BRANCH: ${{ github.head_ref || github.ref_name }} | |
| IS_RELEASE_TAG: ${{ startsWith(github.ref, 'refs/tags/v') }} | |
| GITHUB_REPOSITORY: ${{ github.repository }} | |
| NOTEBOOKS_DIR: tutorials | |
| jobs: | |
| # Job 1: Build the static files for the documentation site | |
| build-deploy-docs: | |
| strategy: | |
| matrix: | |
| os: [macos-14] # Use macOS to switch to dark mode for Plotly charts | |
| runs-on: ${{ matrix.os }} | |
| permissions: | |
| contents: write # required for pushing to gh-pages branch | |
| steps: | |
| # Setting DOCS_VERSION to be used in mkdocs.yml, and then in the | |
| # main.html template. It defines the versioned docs subfolder name | |
| # in the gh-pages branch. If it's a release tag, use the version | |
| # number without the 'v' prefix, otherwise use 'dev'. | |
| # Setting RELEASE_VERSION to be used in mkdocs.yml to show | |
| # the latest release version in the index.md file. If it's a | |
| # release tag, use the tag name, otherwise use the branch name | |
| # for development builds. | |
| - name: Set extra env variables | |
| shell: bash | |
| run: | | |
| if [[ "${IS_RELEASE_TAG}" == "true" ]]; then | |
| RELEASE_VERSION="${GITHUB_REF_NAME}" | |
| DOCS_VERSION="${RELEASE_VERSION#v}" | |
| else | |
| RELEASE_VERSION="${CI_BRANCH}" | |
| DOCS_VERSION="dev" | |
| fi | |
| echo "RELEASE_VERSION=${RELEASE_VERSION}" >> "$GITHUB_ENV" | |
| echo "DOCS_VERSION=${DOCS_VERSION}" >> "$GITHUB_ENV" | |
| echo "DEPLOYMENT_URL=https://easyscience.github.io/${{ github.event.repository.name }}/${DOCS_VERSION}" >> "$GITHUB_ENV" | |
| - name: Check-out repository | |
| uses: actions/checkout@v5 | |
| with: | |
| fetch-depth: 0 # full history with tags; needed for mike to push/deploy docs | |
| # 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: Set up pixi | |
| uses: prefix-dev/setup-pixi@v0.9.0 | |
| with: | |
| environments: default | |
| activate-environment: default | |
| run-install: true | |
| frozen: true | |
| cache: false | |
| post-cleanup: false | |
| - name: Install and setup development dependencies | |
| shell: bash | |
| run: pixi run dev | |
| - name: Clone easyscience/assets-docs and easyscience/assets-branding | |
| run: | | |
| cd .. | |
| git clone https://github.com/easyscience/assets-docs.git | |
| git clone https://github.com/easyscience/assets-branding.git | |
| - name: Add files from cloned repositories | |
| run: pixi run docs-assets | |
| # Convert python scripts in the notebooks directory to Jupyter notebooks | |
| # Strip output from the notebooks | |
| # Prepare the notebooks for documentation (add colab cell, etc.) | |
| # Run the notebooks to generate the output cells using multiple cores | |
| # The notebooks are then used to build the documentation site | |
| - name: Convert tutorial scripts to notebooks | |
| run: pixi run notebook-prepare | |
| # 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: pixi run python -c "import easydiffraction" | |
| # Run the notebooks to generate the output cells using multiple cores | |
| - name: Run notebooks | |
| # if: false # Temporarily disabled to speed up the docs build | |
| run: pixi run notebook-exec | |
| - name: Move notebooks to docs/tutorials | |
| run: pixi run docs-notebooks | |
| # 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: pixi run docs-config | |
| # Build the static files for the documentation site for local inspection | |
| # Input: docs/ directory containing the Markdown files | |
| # Output: site/ directory containing the generated HTML files | |
| - name: Build site for local check | |
| run: pixi run docs-local | |
| # Upload the static files from the site/ directory to be used for | |
| # local check | |
| - name: Upload built site as artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: site-local_edl-${{ env.RELEASE_VERSION }} | |
| path: site/ | |
| if-no-files-found: 'error' | |
| compression-level: 0 | |
| # Publish versioned docs with Mike (dev on branches, prod on tags) | |
| # Configure git for pushing to gh-pages branch | |
| - name: Configure git for pushing | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "41898282+github-actions[bot]@users.noreply.github.com" | |
| # Publish versioned docs with Mike. The tagged release docs go to | |
| # the versioned prefix, e.g. /v1.2.3/, and also to /latest/. | |
| # All other branches go to /dev/. | |
| # "${RELEASE_VERSION#v}" for v0.8.3.post1 -> 0.8.3.post1 | |
| - name: Rebuild and deploy docs with mike | |
| run: | | |
| if [[ "${IS_RELEASE_TAG}" == "true" ]]; then | |
| pixi run docs-deploy "${RELEASE_VERSION#v}" latest | |
| else | |
| pixi run docs-deploy dev | |
| fi | |
| pixi run docs-set-default latest | |
| echo "🔗 deployment url [${{ env.DEPLOYMENT_URL }}](${{ env.DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY |