Refactor core objects, improve validation, and update API #31
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) | |
| # GITHUB_REPOSITORY - the repository name (used in mkdocs.yml) | |
| # NOTEBOOKS_DIR - the directory containing the Jupyter notebooks (used in mkdocs.yml) | |
| CI_BRANCH: ${{ github.head_ref || github.ref_name }} | |
| GITHUB_REPOSITORY: ${{ github.repository }} | |
| NOTEBOOKS_DIR: tutorials | |
| DEV_DEPLOYMENT_URL: | |
| https://easyscience.github.io/${{ github.event.repository.name }} | |
| PROD_DEPLOYMENT_URL: https://docs.easydiffraction.org/lib | |
| jobs: | |
| # Job 1: Build the static files for the documentation site | |
| build-docs: | |
| strategy: | |
| matrix: | |
| os: [macos-14] # Use macOS to switch to dark mode for Plotly charts | |
| runs-on: ${{ matrix.os }} | |
| steps: | |
| - name: Check-out repository | |
| uses: actions/checkout@v5 | |
| 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: Set RELEASE_VERSION env variable (latest easydiffraction release) | |
| run: | | |
| git fetch --tags --force | |
| 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: Set up pixi | |
| uses: prefix-dev/[email protected] | |
| 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 | |
| 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 | |
| # Input: docs/ directory containing the Markdown files | |
| # Output: site/ directory containing the generated HTML files | |
| - name: Build site with MkDocs | |
| run: pixi run docs-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 | |
| # It can also be downloaded using the actions/download-artifact, as the current upload-pages-artifact | |
| # is a wrapper which triggers the actions/upload-artifact. | |
| - name: Upload built site as artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site/ | |
| # Job 2: Deploy the built static files to GitHub Pages (DEV deployment) | |
| deploy-dev: | |
| 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-dev' | |
| cancel-in-progress: false | |
| # Deploy to the github-pages environment | |
| environment: | |
| name: github-pages # Environment name | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| runs-on: ubuntu-latest | |
| # Triggered on push to develop or master branch only | |
| if: ${{ github.ref_name == 'develop' || github.ref_name == 'master' }} | |
| 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 | |
| # Deployed pages are available at https://easyscience.github.io/diffraction-lib | |
| - name: DEV deployment | |
| uses: actions/deploy-pages@v4 | |
| - name: Add DEV deployment url to summary | |
| run: | |
| echo "🔗 DEV deployment url [${{ env.DEV_DEPLOYMENT_URL }}](${{ | |
| env.DEV_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY | |
| # Job 3: Deploy the built static files to GitHub Pages (PROD deployment) | |
| deploy-prod: | |
| needs: deploy-dev # previous job 'deploy-dev' needs to be finished first | |
| # Grant GITHUB_TOKEN the permissions required to make a Pages deployment | |
| permissions: | |
| contents: read | |
| # 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-prod' | |
| cancel-in-progress: false | |
| runs-on: ubuntu-latest | |
| # Triggered on tagged releases only (tags starting with 'v', e.g., v1.0.3) | |
| if: startsWith(github.ref, 'refs/tags/v') | |
| steps: | |
| # Download built site as artifact from a previous job for gh_pages (tagged release) | |
| # This artifact is used to push its content to gh_pages branch for custom domain deployment. | |
| - name: Download built site from previous job | |
| uses: actions/download-artifact@v4 | |
| with: # name or path are taken from the upload step of the previous job | |
| name: github-pages | |
| 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_ACCESS_TOKEN must be set for this repository via | |
| # https://github.com/easyscience/diffraction-lib/settings/secrets/actions | |
| # 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 | |
| - name: PROD deployment to gh_pages for custom domain | |
| uses: s0/git-publish-subdir-action@develop | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCESS_TOKEN }} | |
| REPO: self | |
| BRANCH: gh_pages | |
| FOLDER: site | |
| - name: Show PROD deployment url | |
| if: startsWith(github.ref, 'refs/tags/v') | |
| run: | |
| echo "🔗 PROD deployment url [${{ env.PROD_DEPLOYMENT_URL }}](${{ | |
| env.PROD_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY |