|
| 1 | +name: Build and deploy docs |
| 2 | + |
| 3 | +on: |
| 4 | + # Trigger the workflow on push |
| 5 | + push: |
| 6 | + # To the develop and master branches |
| 7 | + branches: [develop, master] |
| 8 | + |
| 9 | + # Allows you to run this workflow manually from the Actions tab |
| 10 | + workflow_dispatch: |
| 11 | + |
| 12 | +env: |
| 13 | + # Set the environment variables to be used in all jobs defined in this workflow |
| 14 | + # Set the CI_BRANCH environment variable to be the branch name |
| 15 | + # NOTE: Use the same branch name as the one of easyscience/diffraction-lib. This is |
| 16 | + # required to download the Jupyter notebooks from the easyscience/diffraction-lib repository |
| 17 | + # Set the NOTEBOOKS_DIR environment variable to be the directory containing the Jupyter notebooks |
| 18 | + CI_BRANCH: ${{ github.head_ref || github.ref_name }} |
| 19 | + NOTEBOOKS_DIR: examples |
| 20 | + |
| 21 | +jobs: |
| 22 | + # Job 1: Build the static files for the documentation site |
| 23 | + build-docs: |
| 24 | + runs-on: macos-14 # Use macOS to switch to dark mode for Plotly charts |
| 25 | + |
| 26 | + steps: |
| 27 | + - name: Cancel previous workflow runs |
| 28 | + uses: n1hility/cancel-previous-runs@v2 |
| 29 | + with: |
| 30 | + token: ${{ secrets.GITHUB_TOKEN }} |
| 31 | + |
| 32 | + # Without this step, GITHUB_REPOSITORY is not accessible from mkdocs.yml |
| 33 | + - name: Get GitHub repository |
| 34 | + run: echo "GITHUB_REPOSITORY=$GITHUB_REPOSITORY" >> $GITHUB_ENV |
| 35 | + |
| 36 | + # Save the latest release version of easyscience/diffraction-lib to RELEASE_VERSION |
| 37 | + # RELEASE_VERSION is used in the mkdocs.yml file to set release_version. |
| 38 | + # The release_version is then needed to display the latest release version in the index.md file |
| 39 | + - name: Get the latest release version of EasyDiffraction Library |
| 40 | + # This method is not working in CI with the following error: "API rate limit exceeded..." |
| 41 | + #run: echo "RELEASE_VERSION=$(curl https://api.github.com/repos/easyscience/diffraction-lib/releases/latest | grep -i 'tag_name' | awk -F '"' '{print $4}')" >> $GITHUB_ENV |
| 42 | + # This method is not optimal and takes some more time to run, but it works and it is reliable |
| 43 | + run: | |
| 44 | + git clone --depth 1 https://github.com/easyscience/EasyDiffractionLib . |
| 45 | + git fetch --tags |
| 46 | + echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV |
| 47 | +
|
| 48 | + # Activate dark mode to create documentation with Plotly charts in dark mode |
| 49 | + # Need a better solution to automatically switch the chart colour theme based on the mkdocs material switcher |
| 50 | + # Something similar to mkdocs_plotly_plugin https://haoda-li.github.io/mkdocs-plotly-plugin/, |
| 51 | + # but for generating documentation from notepads |
| 52 | + - name: Activate dark mode |
| 53 | + run: | |
| 54 | + brew install dark-mode |
| 55 | + dark-mode status |
| 56 | + dark-mode on |
| 57 | + dark-mode status |
| 58 | +
|
| 59 | + - name: Check-out repository |
| 60 | + uses: actions/checkout@v4 |
| 61 | + |
| 62 | + - name: Set up Python environment |
| 63 | + uses: actions/setup-python@v4 |
| 64 | + with: |
| 65 | + python-version: '3.12' |
| 66 | + |
| 67 | + - name: Upgrade package installer for Python |
| 68 | + run: python -m pip install --upgrade pip |
| 69 | + |
| 70 | + # Install MkDocs -- static site generator |
| 71 | + # https://www.mkdocs.org |
| 72 | + - name: Install MkDocs and its dependencies |
| 73 | + run: > |
| 74 | + pip install mkdocs mkdocs-material 'mkdocs-autorefs<1.3.0' |
| 75 | + mkdocs-jupyter mkdocs-plugin-inline-svg |
| 76 | + mkdocs-markdownextradata-plugin mkdocstrings-python |
| 77 | +
|
| 78 | + # Install EasyDiffraction Library to run Jupyter notebooks |
| 79 | + # Install with the 'charts' and 'docs' extras |
| 80 | + - name: Install EasyDiffraction Library and its dependencies |
| 81 | + run: pip install 'easydiffraction[charts]' |
| 82 | + |
| 83 | + # Download and add the extra files from the easyscience/assets-docs repository |
| 84 | + - name: Get easyscience/assets-docs files |
| 85 | + run: | |
| 86 | + git clone https://github.com/easyscience/assets-docs.git |
| 87 | + cp -R assets-docs/docs/assets/ docs/assets/ |
| 88 | + cp -R assets-docs/includes/ includes/ |
| 89 | + cp -R assets-docs/overrides/ overrides/ |
| 90 | +
|
| 91 | + # Download and add the extra files from the easyscience/assets-branding repository |
| 92 | + - name: Get easyscience/assets-branding files |
| 93 | + run: | |
| 94 | + git clone https://github.com/easyscience/assets-branding.git |
| 95 | + mkdir -p docs/assets/images/ |
| 96 | + cp assets-branding/EasyDiffraction/logos/ed-logo_dark.svg docs/assets/images/ |
| 97 | + cp assets-branding/EasyDiffraction/logos/ed-logo_light.svg docs/assets/images/ |
| 98 | + cp assets-branding/EasyDiffraction/logos/edl-logo_dark.svg docs/assets/images/logo_dark.svg |
| 99 | + cp assets-branding/EasyDiffraction/logos/edl-logo_light.svg docs/assets/images/logo_light.svg |
| 100 | + cp assets-branding/EasyDiffraction/icons/ed-icon_256x256.png docs/assets/images/favicon.png |
| 101 | + mkdir -p overrides/.icons/ |
| 102 | + cp assets-branding/EasyDiffraction/icons/ed-icon_bw.svg overrides/.icons/easydiffraction.svg |
| 103 | + cp assets-branding/EasyScienceOrg/icons/eso-icon_bw.svg overrides/.icons/easyscience.svg |
| 104 | +
|
| 105 | + # Copy Jupyter notebooks from the project to the docs folder |
| 106 | + # The notebooks are used to generate the documentation |
| 107 | + - name: |
| 108 | + Copy Jupyter notebooks from ${{ env.NOTEBOOKS_DIR }}/ to docs/${{ |
| 109 | + env.NOTEBOOKS_DIR }}/ |
| 110 | + run: cp -R ${{ env.NOTEBOOKS_DIR }}/ docs/${{ env.NOTEBOOKS_DIR }}/ |
| 111 | + |
| 112 | + # The following step is needed to avoid the following message during the build: |
| 113 | + # "Matplotlib is building the font cache; this may take a moment" |
| 114 | + - name: Pre-build site step |
| 115 | + run: python -c "import easydiffraction" |
| 116 | + |
| 117 | + # Create the mkdocs.yml configuration file |
| 118 | + # The file is created by merging two files: |
| 119 | + # - assets-docs/mkdocs.yml - the common configuration (theme, plugins, etc.) |
| 120 | + # - docs/mkdocs.yml - the project-specific configuration (project name, TOC, etc.) |
| 121 | + - name: Create mkdocs.yml file |
| 122 | + run: cat ../assets-docs/mkdocs.yml docs/mkdocs.yml > mkdocs.yml |
| 123 | + |
| 124 | + # Build the static files |
| 125 | + # Input: docs/ directory containing the Markdown files |
| 126 | + # Output: site/ directory containing the generated HTML files |
| 127 | + - name: Build site with MkDocs |
| 128 | + run: | |
| 129 | + export JUPYTER_PLATFORM_DIRS=1 |
| 130 | + mkdocs build |
| 131 | +
|
| 132 | + # Set up the Pages action to configure the static files to be deployed |
| 133 | + # NOTE: The repository must have GitHub Pages enabled and configured to build using GitHub Actions |
| 134 | + # This can be done via https://github.com/easyscience/diffraction-lib/settings/pages |
| 135 | + # Select: Build and deploy - Source - GitHub Actions |
| 136 | + - name: Setup GitHub Pages |
| 137 | + uses: actions/configure-pages@v5 |
| 138 | + |
| 139 | + # Upload the static files from the site/ directory to be used in the next job |
| 140 | + # This artifact is named github-pages and is a single gzip archive containing a single tar file |
| 141 | + # The artifact is then used in the next job by actions/deploy-pages to deploy the static files to GitHub Pages |
| 142 | + # Unfortunately, the artifact is not available for download, so extra steps below are needed to do similar things |
| 143 | + - name: |
| 144 | + Upload built site as artifact for |
| 145 | + easyscience.github.io/diffraction-lib (all branches) |
| 146 | + uses: actions/upload-pages-artifact@v3 |
| 147 | + with: |
| 148 | + path: site/ |
| 149 | + |
| 150 | + # Upload the static files from the site/ directory to be used in the next job |
| 151 | + # This extra step is needed to allow the download of the artifact in the next job |
| 152 | + # for pushing its content to the branch named 'easydiffraction.org' |
| 153 | + - name: |
| 154 | + Upload built site as artifact for gh_pages and easydiffraction.org |
| 155 | + (master branch) |
| 156 | + if: ${{ env.CI_BRANCH == 'master' }} |
| 157 | + uses: actions/upload-artifact@v4 |
| 158 | + with: |
| 159 | + name: artifact # name of the artifact (without the extension zip) |
| 160 | + path: site/ |
| 161 | + if-no-files-found: 'error' |
| 162 | + compression-level: 0 |
| 163 | + |
| 164 | + # Job 2: Deploy the static files |
| 165 | + deploy-docs: |
| 166 | + needs: build-docs # previous job 'build-docs' need to be finished first |
| 167 | + |
| 168 | + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment |
| 169 | + permissions: |
| 170 | + contents: read |
| 171 | + pages: write # to deploy to Pages |
| 172 | + id-token: write # to verify the deployment, originates from an appropriate source |
| 173 | + |
| 174 | + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. |
| 175 | + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. |
| 176 | + concurrency: |
| 177 | + group: 'pages' |
| 178 | + cancel-in-progress: false |
| 179 | + |
| 180 | + # Deploy to the github-pages environment |
| 181 | + environment: |
| 182 | + name: github-pages # Artifact name |
| 183 | + url: ${{ steps.deployment.outputs.page_url }} |
| 184 | + |
| 185 | + runs-on: ubuntu-latest |
| 186 | + |
| 187 | + steps: |
| 188 | + # Deploy the static files created in the previous job to GitHub Pages |
| 189 | + # To allow the deployment of the static files to GitHub Pages, no |
| 190 | + # restrictions on the branch name need to be set for desired branches on |
| 191 | + # https://github.com/easyscience/diffraction-lib/settings/environments |
| 192 | + # Currently, only develop and master branches are allowed to deploy to GitHub Pages |
| 193 | + # Deployed pages are available at https://easyscience.github.io/diffraction-lib |
| 194 | + - name: Deploy to easyscience.github.io/diffraction-lib (all branches) |
| 195 | + uses: actions/deploy-pages@v4 |
| 196 | + |
| 197 | + # Download built site as artifact from a previous job for gh_pages and easydiffraction.org (master branch) |
| 198 | + - name: Download built site from previous job (master branch) |
| 199 | + if: ${{ env.CI_BRANCH == 'master' }} |
| 200 | + uses: actions/download-artifact@v4 |
| 201 | + with: # name or path are taken from the upload step of the previous job |
| 202 | + name: artifact |
| 203 | + path: site/ # directory to extract downloaded zipped artifacts |
| 204 | + |
| 205 | + # Push the site files created in the previous job to the gh_pages branch |
| 206 | + # To be able to push to the gh_pages branch, the personal GitHub API access |
| 207 | + # token GH_API_PERSONAL_ACCSESS_TOKEN must be set for this repository via |
| 208 | + # https://github.com/easyscience/diffraction-lib/settings/secrets/actions |
| 209 | + # This branch is used to deploy the site to the custom domain https://easydiffraction.org |
| 210 | + # Deploying is done with a webhook: https://github.com/easyscience/diffraction-lib/settings/hooks |
| 211 | + # This is done for the gh_pages branch when the site is tested with a step above |
| 212 | + - name: |
| 213 | + Deploy to gh_pages branch to trigger deployment to easydiffraction.org |
| 214 | + (master branch) |
| 215 | + if: ${{ env.CI_BRANCH == 'master' }} |
| 216 | + uses: s0/git-publish-subdir-action@develop |
| 217 | + env: |
| 218 | + GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACCSESS_TOKEN }} |
| 219 | + REPO: self |
| 220 | + BRANCH: gh_pages |
| 221 | + FOLDER: site |
0 commit comments