common-python-tasks/.github/workflows/docs-deploy.yml at main · ci-sourcerer/common-python-tasks · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
name: docs-deploy

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
    paths:
      - '.github/workflows/docs.yml'
      - '.github/workflows/docs-deploy.yml'
      - 'docs/**'
      - 'zensical.toml'
      - 'pyproject.toml'
      - 'src/common_python_tasks/tasks.py'
  workflow_dispatch:
    inputs:
      source_ref:
        description: Optional tag or commit to build for a manual version deployment
        required: false
        default: ''
        type: string
      docs_version:
        description: Optional version identifier, such as 0.12
        required: false
        default: ''
        type: string
      docs_version_title:
        description: Optional version title, such as 0.12.1
        required: false
        default: ''
        type: string
      update_latest:
        description: Move the latest alias to this version
        required: false
        default: false
        type: boolean
      default_version:
        description: Optional version or alias used as the site root
        required: false
        default: ''
        type: string

concurrency:
  group: github-pages
  cancel-in-progress: false

jobs:
  metadata:
    name: Resolve documentation version
    runs-on: ubuntu-latest
    outputs:
      aliases: ${{ steps.metadata.outputs.aliases }}
      checkout_ref: ${{ steps.metadata.outputs.checkout_ref }}
      default_version: ${{ steps.metadata.outputs.default_version }}
      version: ${{ steps.metadata.outputs.version }}
      version_title: ${{ steps.metadata.outputs.version_title }}
    steps:
      - name: Resolve version metadata
        id: metadata
        env:
          DEFAULT_VERSION: ${{ inputs.default_version }}
          DOCS_VERSION: ${{ inputs.docs_version }}
          DOCS_VERSION_TITLE: ${{ inputs.docs_version_title }}
          REF_NAME: ${{ github.ref_name }}
          REF_TYPE: ${{ github.ref_type }}
          SOURCE_REF: ${{ inputs.source_ref }}
          UPDATE_LATEST: ${{ inputs.update_latest }}
        run: |
          if [[ -n "$DOCS_VERSION" ]]; then
            manual_inputs="$DOCS_VERSION$DOCS_VERSION_TITLE$SOURCE_REF$DEFAULT_VERSION"
            if [[ "$manual_inputs" == *$'\n'* || "$manual_inputs" == *$'\r'* ]]; then
              echo 'Manual documentation inputs cannot contain newlines.' >&2
              exit 2
            fi
            if [[ "$UPDATE_LATEST" == "true" ]]; then
              aliases='["latest"]'
            else
              aliases='[]'
            fi
            {
              echo "aliases=$aliases"
              echo "checkout_ref=$SOURCE_REF"
              echo "default_version=$DEFAULT_VERSION"
              echo "version=$DOCS_VERSION"
              echo "version_title=$DOCS_VERSION_TITLE"
            } >> "$GITHUB_OUTPUT"
          elif [[ "$REF_TYPE" == "tag" ]]; then
            if [[ ! "$REF_NAME" =~ ^v?([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
              echo "Stable documentation tags must use vMAJOR.MINOR.PATCH: $REF_NAME" >&2
              exit 2
            fi
            {
              echo 'aliases=["latest"]'
              echo 'checkout_ref='
              echo 'default_version=latest'
              echo "version=${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
              echo "version_title=${REF_NAME#v}"
            } >> "$GITHUB_OUTPUT"
          else
            {
              echo 'aliases=[]'
              echo 'checkout_ref='
              echo 'default_version='
              echo 'version=dev'
              echo 'version_title=Development'
            } >> "$GITHUB_OUTPUT"
          fi

  docs:
    needs: metadata
    uses: ./.github/workflows/docs.yml
    with:
      python_version: '3.14'
      dependency_group: ''
      locked: false
      artifact_name: common-python-tasks-docs
      checkout_ref: ${{ needs.metadata.outputs.checkout_ref }}
      generated_docs_check_task: check-docs-references
      deploy_github_pages: true
      docs_version: ${{ needs.metadata.outputs.version }}
      docs_version_title: ${{ needs.metadata.outputs.version_title }}
      docs_aliases: ${{ needs.metadata.outputs.aliases }}
      docs_default_version: ${{ needs.metadata.outputs.default_version }}
    permissions:
      contents: write
      deployments: write
      pages: write
      id-token: write