hexdoc/.github/workflows/hexdoc.yml at main · hexdoc-dev/hexdoc · 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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
name: "[Reusable] Build and publish a hexdoc plugin with a web book"

on:
  workflow_call:
    inputs:
      python-version:
        description: Python version to install
        type: string
        required: true
      release:
        description: If the book should be written to the release path or the latest path
        type: boolean
        required: true
      props:
        description: Path to your props file (hexdoc.toml or properties.toml)
        type: string
        required: false
      pip-extras:
        description: Pip extras for your package (eg. [dev])
        type: string
        required: false
      deploy-pages:
        description: If the workflow should deploy to GitHub Pages
        type: boolean
        default: true
      subdirectory:
        description: Subdirectory to deploy the book to
        type: string
        required: false
      site-url:
        description: Set the base site url instead of looking up the current repo's GitHub Pages url
        type: string
        required: false
      bump-version-segment:
        description: DEPRECATED - This value no longer does anything and is only kept for backwards compatibility.
        type: string
        required: false
    secrets:
      GH_TOKEN:
        required: true
    outputs:
      pages-url:
        description: Current GitHub Pages url for this repo
        value: ${{ jobs.build.outputs.pages-url }}
      release:
        description: Value of inputs.release for convenience
        value: ${{ inputs.release }}

permissions:
  contents: read

env:
  HEXDOC_PROPS: ${{ inputs.props }}
  HEXDOC_RELEASE: ${{ inputs.release }}
  HEXDOC_SUBDIRECTORY: ${{ inputs.subdirectory }}
  GITHUB_PAGES_URL: ${{ inputs.site-url }}

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
    permissions:
      contents: read
      pages: read
    outputs:
      pages-url: ${{ steps.export.outputs.pages-url }}

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: ${{ inputs.python-version }}
          cache: pip
      - uses: yezz123/setup-uv@v4

      - name: Install display server
        uses: awalsh128/cache-apt-pkgs-action@v1
        with:
          packages: xvfb

      - name: Install Python packages
        run: uv pip install --system -e .${{ inputs.pip-extras }} hatch

      - name: Build web book
        id: export
        run: xvfb-run --auto-servernum hexdoc ci build

      - name: Zip web book
        working-directory: _site/src/docs
        run: zip site.zip ./* -r

      - name: Upload intermediate Pages artifact
        uses: actions/upload-artifact@v3
        with:
          name: hexdoc-pages
          path: _site/src/docs/site.zip

      - name: Upload package artifact
        uses: actions/upload-artifact@v3
        with:
          name: hexdoc-build
          path: dist

      - name: Add job summary
        run: echo "Built version \`$(hatch version)\` from commit \`$(git rev-parse --short "$GITHUB_SHA")\`." >> $GITHUB_STEP_SUMMARY

  deploy-pages:
    needs: build
    if: inputs.deploy-pages
    runs-on: ubuntu-latest
    concurrency:
      group: hexdoc-deploy-pages
      cancel-in-progress: false
    permissions:
      contents: write
    env:
      GITHUB_PAGES_URL: ${{ needs.build.outputs.pages-url }}

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: ${{ inputs.python-version }}
          cache: pip
      - uses: yezz123/setup-uv@v4

      - name: Install Python packages
        run: uv pip install --system -e .${{ inputs.pip-extras }}

      - name: Download Pages artifact
        uses: actions/download-artifact@v3
        with:
          name: hexdoc-pages

      - name: Unzip web book
        run: |
          mkdir -p _site/src
          unzip site.zip -d _site/src/docs

      - name: Checkout current Pages
        uses: actions/checkout@v3
        continue-on-error: true
        with:
          ref: gh-pages
          path: _site/dst

      - name: Merge web book
        run: hexdoc ci merge

      - name: Deploy to Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: _site/dst/docs/${{ inputs.subdirectory }}
          target-folder: docs/${{ inputs.subdirectory }}
          clean: true
          clean-exclude: |
            CNAME
            .gitignore