policy_docs.yml

#################################
## DOCS STATIC SITE Build/Test ##
##      Reusable Workflow      ##
#################################

### TOOLS ###
# - mkdocs
# - sphinx

## AUTONOMOUS JOB ##

#  0. Never run
#  1. Always run
#  2. Run Docs on conditions
#     - Triggered on a Long-living branch (ie main)
#     - Triggered on a v* tag (ie v1.0.0)
#     - Docs Source Files (ie docs/) changed, compared to previous commit
#  3. Run Docs, if Source Files changed, compared to previous commit

on:
  workflow_call:
    inputs:
      # Defaults to Policy 2 (CI/CD)
      run_policy:
        default: '2'
        type: string
        description: 'Policy for when to run Docs Build'
        required: false
      dedicated_branches:
        default: 'main, master, dev'
        type: string
        description: "Branches to always want to run Docs Build. Has effect only on Policy '2'"
        required: false
      source_code_targets:
        default: 'docs/'
        type: string
        required: false
        description: "Comma separated list of folders to watch for changes. Has effect only on Policy '2' and '3'"
      ## BUILD COMMAND
      command:
        default: 'tox -e docs --sitepackages -vv -s false'
        type: string
        description: 'Docs Build Command to run'
        required: false
      ## Parametrizing Runtime Environment (ie py version)
      python_version:
        default: '3.10'
        type: string
        description: 'Python Interpreter Version to use for Docs Build Environment'
        required: false

jobs:
  docs_policy:
    name: "Run Docs Workflow/Job?"
    runs-on: ubuntu-latest
    if: always() && inputs.run_policy != 0
    steps:
      - if: ${{ !contains('1, 2, 3', inputs.run_policy) }}
        run: 'echo "Invalid run_policy: ${{ inputs.run_policy }}. Must be >0 and <4" && exit 1'

      - if: inputs.run_policy == 1
        name: 'POLICY: 1 -> Trigger'
        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV

      - if: inputs.run_policy == 2 && contains(inputs.dedicated_branches, github.ref_name)
        name: 'POLICY: 2 & Branch: ${{ github.ref_name }} -> Trigger'
        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV

      - if: inputs.run_policy == 2 && startsWith(github.ref, 'refs/tags/v')
        name: 'POLICY: 2 & Tag: ${{ github.ref_name }} -> Trigger'
        run: echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV

      - if: ${{ env.SHOULD_RUN_DOCS != 'true' && contains('2, 3', inputs.run_policy) }}
        name: 'POLICY: 2, 3 -> Derive from DIFF'
        run: echo "SHOULD_DERIVE_FROM_DIFF=true" >> $GITHUB_ENV

      - if: ${{ env.SHOULD_DERIVE_FROM_DIFF }}
        name: 'POLICY: 2, 3 -> Checkout Code to compute DIFF'
        uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - if: ${{ env.SHOULD_DERIVE_FROM_DIFF }}
        name: 'POLICY: 2, 3 -> Check Docs Source Files DIFF'
        run: |
          echo "============ List Modified Files ============"
          git diff --name-only HEAD^ HEAD
          CHANGED_FILES=$(git diff --name-only HEAD^ HEAD)

          # Read Folders we 'Watch' for changes
          TARGETS=$(echo "${{ inputs.source_code_targets }}" | tr ',' '\n')

          # Loop through the Watched Folders
          for TARGET in $TARGETS; do
            # if rel path of changed file matches glob pattern
            if [[ $CHANGED_FILES == *"$TARGET"* ]]; then
              echo "SHOULD_RUN_DOCS=true" >> $GITHUB_ENV
              echo " --> DOCS Change, from previous commit, found: $TARGET"
              break
            fi
          done

      ### OUTPUT of JOB ###
      - name: "Set 'Run Docs' Signal to ${{ env.SHOULD_RUN_DOCS }}"
        id: set_docs_signal
        run: echo "RUN_DOCS=${{ env.SHOULD_RUN_DOCS }}" >> $GITHUB_OUTPUT
    outputs:
      RUN_DOCS: ${{ steps.set_docs_signal.outputs.RUN_DOCS }}

  docs:
    name: "Docs: Build & Test"
    runs-on: ubuntu-latest
    needs: docs_policy
    if: always() && needs.docs_policy.outputs.RUN_DOCS == 'true'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ inputs.python_version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ inputs.python_version }}
      - name: Install Tox
        run: |
          python -m pip install --upgrade pip
          python -m pip install tox==3.28

      - name: Install Build dependencies
        if: ${{ matrix.platform == 'macos-latest' && matrix.python-version != '3.6' }}
        run: brew install enchant

      - name: Build Documentation and Test
        if: ${{ matrix.platform == 'ubuntu-latest' || matrix.python-version  != '3.6' }}
        run: ${{ inputs.command }}
        # run: tox -e docs --sitepackages -vv -s false