Deploy documentation from a pull request#

Note

In versions earlier than v10.2, this action required you to include the closed GitHub event in on.pull_request.types to trigger documentation cleanup when a PR was closed. Starting with version v10.2, this requirement is removed. Documentation cleanup now happens automatically in the background. The cleanup process uses ansys/actions/doc-deploy-dev, so make sure that your workflows also use version v10.2 or later of ansys/actions/doc-deploy-dev.

The ansys/action/doc-deploy-pr action automates the deployment of HTML documentation from a pull request (PR) and its removal when the PR is closed.

The maximum-pr-doc-deployments input limits the number of active documentation deployments, which is useful for repositories with multiple PRs. You can further control deployments using a labeling strategy.

The action automatically adds the following comments to PRs:

A URL to the deployed documentation.
Confirmation of documentation removal for closed PRs.
A notification if maximum-pr-doc-deployments is exceeded.

Two setup options are provided based on the desired level of control:

Basic Setup

Deploy documentation for every PR, provided the maximum-pr-doc-deployments limit is not exceeded. This setup is ideal for documentation-focused projects. Add the following to your workflow file:

For versions prior to v10.2

on:
  pull_request:
    types: [opened, reopened, synchronize, edited, closed]

jobs:
  doc-build:
    name: "Doc build"
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/doc-build@v10.1
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  doc-deploy-pr:
    name: "Deploy PR documentation"
    runs-on: ubuntu-latest
    needs: doc-build
    if: always() && (needs.doc-build.result == 'success' || needs.doc-build.result == 'skipped')
    steps:
      - uses: ansys/actions/doc-deploy-pr@v10.1
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
          maximum-pr-doc-deployments: 10

For versions after v10.2

on:
  pull_request:
    types: [opened, reopened, synchronize, edited]

jobs:
  doc-build:
    name: "Doc build"
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/doc-build@v10.2
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  doc-deploy-pr:
    name: "Deploy PR documentation"
    runs-on: ubuntu-latest
    needs: doc-build
    steps:
      - uses: ansys/actions/doc-deploy-pr@v10.2
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
          maximum-pr-doc-deployments: 10

Setup with Labeling Strategy

Deploy documentation only for PRs explicitly labeled for deployment. This setup is recommended for libraries where deploying documentation for all PRs may not be necessary.

Steps:

Add a label to .github/labels.yml:

- name: 'deploy-pr-doc'
  description: Deploy pull request documentation
  color: 00ff00

Add the label to .github/labeler.yml to prevent its removal:

# HACK: the label is declared with the only purpose of avoiding the
# GitHub labeler bot from removing it. This is a known issue reported in the
# official action/labeler repo https://github.com/actions/labeler/issues/763
'deploy-pr-doc':
  - all:
      - changed-files:
          - all-globs-to-all-files: ['THIS-NEVER-MATCHES-A-FILE']

Update your workflow file:

For versions prior to v10.2

on:
  pull_request:
    types: [opened, reopened, synchronize, edited, labeled, closed]

jobs:
  doc-build:
    name: "Doc build"
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/doc-build@v10.1
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  doc-deploy-pr:
    name: "Deploy PR documentation"
    runs-on: ubuntu-latest
    needs: doc-build
    if: |
      always() &&
      (needs.doc-build.result == 'success' || needs.doc-build.result == 'skipped') &&
      contains(github.event.pull_request.labels.*.name, 'deploy-pr-doc')
    steps:
      - uses: ansys/actions/doc-deploy-pr@v10.1
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
          maximum-pr-doc-deployments: 10

For versions after v10.2

on:
  pull_request:
    types: [opened, reopened, synchronize, edited, labeled]

jobs:
  doc-build:
    name: "Doc build"
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/doc-build@v10.2
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  doc-deploy-pr:
    name: "Deploy PR documentation"
    runs-on: ubuntu-latest
    needs: doc-build
    if: contains(github.event.pull_request.labels.*.name, 'deploy-pr-doc')
    steps:
      - uses: ansys/actions/doc-deploy-pr@v10.2
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}
          maximum-pr-doc-deployments: 10

With this setup, documentation is deployed only when the deploy-pr-doc label is added to a PR. For an example, see this setup for ansys/actions.