Updates NCAF tutorial #18
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
| name: Building and deploying docs | |
| on: | |
| # Trigger the workflow on push | |
| push: | |
| # To the develop and master branches | |
| branches: [develop, master, docs] | |
| # 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 | |
| # Set the NOTEBOOKS_DIR environment variable to be the directory containing the Jupyter notebooks | |
| CI_BRANCH: ${{ github.head_ref || github.ref_name }} | |
| NOTEBOOKS_DIR: tutorials | |
| jobs: | |
| # Job 1: Build the static files for the documentation site | |
| building-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/EasyDiffractionLib 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 | |
| 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@v5 | |
| with: | |
| python-version: '3.12' | |
| - name: Upgrade package installer for Python | |
| run: python -m pip install --upgrade pip | |
| # Install EasyDiffraction Library to run Jupyter notebooks | |
| # Install with the 'charts' and 'docs' extras | |
| - name: Install EasyDiffraction Library and its dependencies | |
| run: pip install -r requirements.txt | |
| # Clone assets extra from: | |
| # - easyscience/assets-docs | |
| # - easyscience/assets-branding | |
| - 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 | |
| # Add the extra files from the easyscience/assets-docs repository | |
| - name: Add files from easyscience/assets-docs files | |
| run: | | |
| cp -R ../assets-docs/docs/assets/ docs/assets/ | |
| cp -R ../assets-docs/includes/ includes/ | |
| cp -R ../assets-docs/overrides/ overrides/ | |
| # Add the extra files from the easyscience/assets-branding repository | |
| - name: Add files from easyscience/assets-branding files | |
| run: | | |
| mkdir -p docs/assets/images/ | |
| 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/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: Convert ${{ env.NOTEBOOKS_DIR }}/*.py to docs/${{env.NOTEBOOKS_DIR }}/*.ipynb | |
| run: | | |
| cp -R ${{ env.NOTEBOOKS_DIR }}/data docs/${{ env.NOTEBOOKS_DIR }}/ | |
| jupytext ${{ env.NOTEBOOKS_DIR }}/*.py --to ipynb | |
| mv ${{ env.NOTEBOOKS_DIR }}/*.ipynb 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: | | |
| export PYTHONPATH=$(pwd)/src:$PYTHONPATH | |
| 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: python tools/create_mkdocs-yml.py | |
| # 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 | |
| export PYTHONWARNINGS="ignore::RuntimeWarning" | |
| export PYTHONPATH=$(pwd)/src:$PYTHONPATH | |
| 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/EasyDiffractionLib (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 'gh_pages' | |
| - name: | |
| Upload built site as artifact for gh_pages (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 | |
| deploying-docs: | |
| needs: building-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 (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. | |
| # 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 custom domain (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 |