diff --git a/.github/workflows/backmerge-pr.yaml b/.github/workflows/backmerge-pr.yaml index ab80d5d0..44d1189d 100644 --- a/.github/workflows/backmerge-pr.yaml +++ b/.github/workflows/backmerge-pr.yaml @@ -7,6 +7,8 @@ # The GitHub App must be added to the develop ruleset bypass list. # # Required repo config: +# https://github.com/organizations/easyscience/settings/secrets/actions +# https://github.com/organizations/easyscience/settings/variables/actions # - Actions secret: ES_BACKMERGE_PRIVATE_KEY (GitHub App private key PEM) # - Actions variable: ES_BACKMERGE_APP_ID (GitHub App ID) @@ -14,8 +16,8 @@ name: Backmerge PR (tag -> develop) on: push: - tags: - - 'v*' + branches: ['**'] + tags: ['v*'] permissions: contents: write @@ -30,8 +32,8 @@ jobs: id: app-token uses: actions/create-github-app-token@v2 with: - app-id: ${{ vars.ES_BACKMERGE_APP_ID }} - private-key: ${{ secrets.ES_BACKMERGE_PRIVATE_KEY }} + app-id: ${{ vars.BACKMERGE_APP_ID }} + private-key: ${{ secrets.BACKMERGE_PRIVATE_KEY }} - name: Checkout tag commit uses: actions/checkout@v5 diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8dd24c1d..23e54ff1 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -7,7 +7,7 @@ # 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*). +# - 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 @@ -40,25 +40,51 @@ concurrency: # 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 DEV_DEPLOYMENT_URL: - https://easyscience.github.io/${{ github.event.repository.name }} + https://easyscience.github.io/${{ github.event.repository.name }}/dev PROD_DEPLOYMENT_URL: https://docs.easydiffraction.org/lib jobs: # Job 1: Build the static files for the documentation site - build-docs: + 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'. + - 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" + - name: Check-out repository uses: actions/checkout@v5 with: @@ -67,10 +93,10 @@ jobs: # 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" + #- 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 @@ -133,124 +159,40 @@ jobs: - name: Create mkdocs.yml file run: pixi run docs-config - # Build the static files + # 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 with MkDocs - run: | - if [[ "${CI_BRANCH}" == "develop" || "${CI_BRANCH}" == "master" || "${CI_BRANCH}" == "main" ]]; then - echo "📘 Building production docs for ${CI_BRANCH}" - pixi run docs-build - else - echo "📗 Building local docs for ${CI_BRANCH}" - pixi run docs-local - fi + - name: Build site for local check + run: pixi run docs-local - # 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. + # Upload the static files from the site/ directory to be used for + # local check - name: Upload built site as artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-artifact@v4 with: + name: site-local_edl-${{ env.RELEASE_VERSION }} path: site/ + if-no-files-found: 'error' + compression-level: 0 - # 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 + # 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 + echo "🔗 PROD deployment url [${{ env.PROD_DEPLOYMENT_URL }}](${{ env.PROD_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY + else + pixi run docs-deploy dev + echo "🔗 DEV deployment url [${{ env.DEV_DEPLOYMENT_URL }}](${{ env.DEV_DEPLOYMENT_URL }})" >> $GITHUB_STEP_SUMMARY + fi + pixi run docs-set-default latest diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 94a2263a..aea235ff 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -3,8 +3,8 @@ ########################### # Project information -site_name: EasyDiffraction Library -site_url: https://docs.easydiffraction.org/lib/ +site_name: '' #EasyDiffraction Library +site_url: https://easyscience.github.io/diffraction-lib/ #https://docs.easydiffraction.org/lib/ # Repository repo_url: https://github.com/easyscience/diffraction-lib/ diff --git a/out.prof b/out.prof deleted file mode 100644 index dec44a3e..00000000 Binary files a/out.prof and /dev/null differ diff --git a/pixi.toml b/pixi.toml index 2cd6bf7d..2fd51c72 100644 --- a/pixi.toml +++ b/pixi.toml @@ -176,6 +176,8 @@ notebook-prepare = { depends-on = [ docs-assets = 'tools/add_assets_to_docs.sh' docs-notebooks = 'mv tutorials/*.ipynb docs/tutorials/' docs-config = 'python tools/create_mkdocs_yml.py' +docs-deploy = 'mike deploy --push --branch gh-pages --update-aliases --alias-type redirect' +docs-set-default = 'mike set-default --push --branch gh-pages' docs-serve = "JUPYTER_PLATFORM_DIRS=1 PYTHONWARNINGS='ignore::RuntimeWarning' python -m mkdocs serve --dirty" docs-build = "JUPYTER_PLATFORM_DIRS=1 PYTHONWARNINGS='ignore::RuntimeWarning' python -m mkdocs build" docs-local = "pixi run docs-build --no-directory-urls" diff --git a/pyproject.toml b/pyproject.toml index d262f0a5..5a3f864e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,6 +64,7 @@ dev = [ 'interrogate', # Check for missing docstrings ] docs = [ + 'mike', # MkDocs: Versioned documentation support 'mkdocs', # Static site generator 'mkdocs-material', # Documentation framework on top of MkDocs 'mkdocs-autorefs<1.3.0', # MkDocs: Auto-references support. 1.3.0 => DeprecationWarning: Setting a fallback anchor function is deprecated and ...