Merge pull request #110 from easyscience/fix-docs

Documentation CI fixes and versioned documentation support

Author: AndrewSazonov

.github/workflows/backmerge-pr.yaml

@@ -30,7 +30,7 @@ jobs:
         id: app-token
         uses: actions/create-github-app-token@v2
         with:
-          app-id: ${{ vars.ES_BACKMERGE_APP_ID }}
+          app-id: ${{ secrets.ES_BACKMERGE_APP_ID }} # in secrets or vars?
           private-key: ${{ secrets.ES_BACKMERGE_PRIVATE_KEY }}
 
       - name: Checkout tag commit

.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

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/

out.prof

@@ -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"

pixi.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 ...