action.yml

# Copyright (C) 2022 - 2024 ANSYS, Inc. and/or its affiliates.
# SPDX-License-Identifier: MIT
#
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

name: >
  Doc deploy dev action

description: |
  This action deploys the desired HTML documentation artifact containing the
  development version of a library to the specified branch of a repository. By
  default, the ``gh-pages`` branch of the current repository is assumed.

inputs:

  # Required inputs

  cname:
    description: >
      The canonical name (CNAME) containing the documentation.
    required: true
    type: string

  token:
    description: >
      Required password, key or token with the correct credentials for deploying the
      documentation. If deploying to the current repository, the ``secrets.GITHUB_TOKEN`` token
      is enough. For workflows deploying to other repositories, `generate and
      use a token with writing access
      <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_
      to that repository.
    required: true
    type: string

  # Optional inputs

  doc-artifact-name:
    description: >
        Name of the HTML documentation artifact. This artifact is expected to
        contain all the HTML and static files. If it contains a compressed file,
        make sure you enable the ``decompress-artifact`` option.
    required: false
    default: 'documentation-html'
    type: string

  decompress-artifact:
    description: >
      Wether to decompress the artifact using `ouch
      <https://github.com/ouch-org/ouch>`_ as decompression tool. Default value
      is ``false``.
    required: false
    default: false
    type: string

  repository:
    description: >
      Repository name in the form of ``username/repository`` to be used for
      deploying the documentation. The current repository is assumed by default.
    required: false
    default: 'current'
    type: string

  branch:
    description: >
      Branch name for deploying the documentation. The ``gh-pages`` branch is
      used by default.
    required: false
    default: 'gh-pages'
    type: string

  commit-message:
    description: >
      Commit message used when deploying the documentation.
    required: false
    default: 'DOC: update development documentation'
    type: string

  force-orphan:
    description: >
      Whether to force the deployment branch to be orphan with only the latest commit or not. Default value
      is ``true``.
    required: false
    default: true
    type: string

  content-element-id:
    description: >
      Identifier of the HTML tag that comprises all the content of the article
      or post.
    required: false
    default: 'main-content'
    type: string

runs:
  using: "composite"
  steps:

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Checkout the repository branch for deploying the documentation. If
          this step fails, then it means that the provided token is not valid.

    - name: "Get the name of the repository"
      shell: bash
      run: |
        if [[ "${{ inputs.repository }}" == "current" ]]; then
          echo "REPOSITORY=${{ github.repository }}" >> $GITHUB_ENV
        else
          echo "REPOSITORY=${{ inputs.repository }}" >> $GITHUB_ENV
        fi

    - name: "Checkout ${{ env.REPOSITORY }} repository"
      uses: actions/checkout@v4
      with:
        repository: ${{ env.REPOSITORY }}
        token: ${{ inputs.token }}

    - name: "Ensure that the desired branch exists"
      env:
        BRANCH: ${{ inputs.branch }}
      shell: bash
      run: |
        # Check the ${{ env.BRANCH }} branch exists on remote
        branch_exists=$(git ls-remote --heads origin refs/heads/${{ env.BRANCH }} 2>&1)

        # If the ${{ env.BRANCH }} doesn't exist, then print error message and exit 1
        if [ -z "$branch_exists" ]; then
          echo "The ${{ env.BRANCH }} branch does not exist. Creating ${{ env.BRANCH }}."

          # Create orphan branch
          git checkout --orphan ${{ env.BRANCH }}

          # Unstage files to be committed
          git rm --cached -r .

          # Remove untracked files
          git clean -fd

          # Configure git username & email
          git config user.name 'pyansys-ci-bot'
          git config user.email 'pyansys.github.bot@ansys.com'

          # Commit ${{ env.BRANCH }} & push to origin
          git commit --allow-empty -m "Create ${{ env.BRANCH }} branch"
          git push -u origin ${{ env.BRANCH }}
        else
          # Fetch and switch to ${{ env.BRANCH }}
          git fetch origin ${{ env.BRANCH }}:${{ env.BRANCH }}
          git switch ${{ env.BRANCH }}
        fi

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Download the documentation artifact from the current workflow. If the
          artifact contains a compressed file, decompress it. Display the
          structure of the 'version/dev' directory at the end of the process to
          verify the layout of the folder is the right one.

    - name: "Clean destination folder"
      shell: bash
      run:
        rm -rf version/dev && mkdir -p version/dev

    - name: "Download the development documentation artifact"
      uses: actions/download-artifact@v4
      with:
        name: ${{ inputs.doc-artifact-name }}
        path: version/dev

    - name: "Update apt-get"
      shell: bash
      run: |
        sudo apt-get update

    - name: "Decompress artifact content"
      shell: bash
      if: inputs.decompress-artifact == 'true'
      run: |
        sudo apt-get install -y cargo && cargo install ouch
        export PATH="$HOME/.cargo/bin/:$PATH"
        ouch --version
        cd version/dev && compressed_artifact=$(ls .)
        ouch decompress $compressed_artifact
        decompressed_artifact=$(ls -I "*${compressed_artifact##*.}")
        mv $decompressed_artifact/* .
        rm -rf $compressed_artifact $decompressed_artifact

    - name: "Display structure of version/dev"
      shell: bash
      run: |
        ls -R version/dev

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Create the 'versions.json' file if it does not exist. Note that this
          step is not required in the 'doc-deploy-stable' action. The reason is
          that for a stable release to be created, a development version must exist. This
          forces users to use this action before using the stable deploy one.

    - name: "Create the 'versions.json' file if not present"
      shell: bash
      run: |
        if ! [[ -f "versions.json" ]];
        then
            sudo apt-get install -y moreutils jq
            echo '[]' > versions.json
            url_dev="https://${{ inputs.cname }}/version/dev/"
            jq --arg url $url_dev '. += [{"name": "dev", "version": "dev", "url": $url}]' versions.json | sponge versions.json
        fi
        cat versions.json

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Include a link canonical tag in old versions if not present.

    - name: "Include link canonical tag in pages"
      uses: ansys/actions/_doc-gen-canonical@v6
      with:
        cname: ${{ inputs.cname }}
        version-directory: version

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Copy the index.html from the stable version and update all
          local href and source links to point to either the stable or dev version.

    - name: "Use the latest 'version/{stable|dev}/index.html' in the landing page"
      shell: bash
      run: |
        if [[ -f 'version/stable/index.html' ]]; then
          cp version/stable/index.html index.html
          sed -i 's/href="\([^:"]*\)"/href="version\/stable\/\1"/g' index.html
          sed -i 's/src="\([^:"]*\)"/src="version\/stable\/\1"/g' index.html
        elif [[ -f 'version/dev/index.html' ]]; then
          cp version/dev/index.html index.html
          sed -i 's/href="\([^:"]*\)"/href="version\/dev\/\1"/g' index.html
          sed -i 's/src="\([^:"]*\)"/src="version\/dev\/\1"/g' index.html
        else
          echo "Error: The 'index.html' file does not exist." >&2
          exit 1
        fi

    - name: "Show the contents of the 'index.html' redirection file"
      shell: bash
      run: |
          cat index.html

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Copy the 'version/stable/index.html' to 'version/index.html' file. If
          no stable release is available, copy the 'dev/index.html' instead.
          Update all references to point to 'stable/_static' or 'dev/_static'.

    - uses: ansys/actions/_doc-gen-versions-page@v6
      with:
        cname: ${{ inputs.cname }}
        content-element-id: ${{ inputs.content-element-id }}

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          Create the '.nojekyll' and 'CNAME' file with the desired values

    - name: "Create '.nojekyll' and 'CNAME' files"
      shell: bash
      run: |
          touch .nojekyll CNAME
          echo "${{ inputs.cname }}" > CNAME

    # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      # Apply this step only if 'version/stable/' dir exists
      if: ${{ hashFiles('version/stable/' != '') }}
      with:
        level: "INFO"
        message: >
          Generate the site-map for the latest development or stable
          documentation.

    - name: "Generate 'sitemap.xml' file"
      uses: ansys/actions/_doc-gen-sitemap@v6
      # Apply this step only if 'version/stable/' dir exists
      if: ${{ hashFiles('version/stable/' != '') }}
      with:
        cname: ${{ inputs.cname }}
        html-directory: version/stable

     # ------------------------------------------------------------------------

    - uses: ansys/actions/_logging@v6
      with:
        level: "INFO"
        message: >
          For deploying the documentation, a GitHub token or a deployment token
          is required. The GitHub token is used when deploying to the current
          repository while the deployment token is used to deploy to an external
          repository.

    - name: "Deploy to ${{ inputs.branch }} branch of ${{ github.repository }} repository"
      if: inputs.repository == 'current'
      uses: peaceiris/actions-gh-pages@v3
      with:
        publish_dir: .
        publish_branch: ${{ inputs.branch }}
        github_token: ${{ inputs.token }}
        commit_message: ${{ inputs.commit-message }}
        keep_files: true
        force_orphan: ${{ inputs.force-orphan }}

    - name: "Deploy to ${{ inputs.branch }} branch of ${{ inputs.repository }}"
      if: inputs.repository != 'current'
      uses: peaceiris/actions-gh-pages@v3
      with:
        publish_dir: .
        publish_branch: ${{ inputs.branch }}
        personal_token: ${{ inputs.token }}
        external_repository: ${{ inputs.repository }}
        commit_message: ${{ inputs.commit-message }}
        keep_files: true
        force_orphan: ${{ inputs.force-orphan }}