homelab/.github/workflows/docs.yml at 21e24e6b3007ee1680ee85d168e3de1a16831b8f · chutch3/homelab · 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
130
131
132
133
134
135
136
137
138
139
140
141
142
name: 📚 Documentation

on:
    workflow_call:
        inputs:
            deploy:
                description: "Deploy to GitHub Pages"
                required: false
                default: true
                type: boolean
    workflow_dispatch:
        inputs:
            deploy:
                description: "Deploy to GitHub Pages (only works on main branch)"
                required: false
                default: true
                type: boolean
            environment:
                description: "Target environment"
                required: false
                default: "github-pages"
                type: choice
                options:
                    - github-pages

permissions:
    contents: read
    pages: write
    id-token: write

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

jobs:
    # Validate documentation on PRs and pushes (non-strict mode)
    validate:
        name: 🔍 Validate Documentation
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0

            - name: Set up Python
              id: setup-python
              uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - name: Install Poetry
              uses: snok/install-poetry@v1
              with:
                  version: latest
                  virtualenvs-create: true
                  virtualenvs-in-project: true

            - name: Load cached dependencies
              id: cached-poetry-dependencies
              uses: actions/cache@v4
              with:
                  path: .venv
                  key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}

            - name: Install Task
              uses: arduino/setup-task@v1
              with:
                  version: 3.x
                  repo-token: ${{ secrets.GITHUB_TOKEN }}

            - name: Install dependencies
              run: task install

            - name: Validate documentation build
              run: task docs:validate

            - name: Upload documentation artifact (for manual runs)
              if: github.event_name == 'workflow_dispatch'
              uses: actions/upload-artifact@v4
              with:
                  name: documentation-manual-${{ github.run_number }}
                  path: ./site
                  retention-days: 7

    # Build and deploy documentation on release or manual triggers
    build-and-deploy:
        name: 🏗️ Build & Deploy Documentation
        if: >-
            github.ref == 'refs/heads/main' &&
            inputs.deploy == true
        needs: validate
        runs-on: ubuntu-latest
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        steps:
            - name: Checkout
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0

            - name: Set up Python
              id: setup-python
              uses: actions/setup-python@v5
              with:
                  python-version: "3.11"

            - name: Install Poetry
              uses: snok/install-poetry@v1
              with:
                  version: latest
                  virtualenvs-create: true
                  virtualenvs-in-project: true

            - name: Load cached dependencies
              id: cached-poetry-dependencies
              uses: actions/cache@v4
              with:
                  path: .venv
                  key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}

            - name: Install Task
              uses: arduino/setup-task@v1
              with:
                  version: 3.x
                  repo-token: ${{ secrets.GITHUB_TOKEN }}

            - name: Install dependencies
              run: task install

            - name: Build documentation (non-strict for deployment)
              run: task docs:validate

            - name: Upload documentation artifacts
              uses: actions/upload-pages-artifact@v3
              with:
                  path: ./site

            - name: Deploy to GitHub Pages
              id: deployment
              uses: actions/deploy-pages@v4