spdx-python-model/.github/workflows/docs.yaml at main · spdx/spdx-python-model · 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
160
---
# Publish library landing page to
# https://spdx.github.io/spdx-python-model/
#
# Publish API docs to
# https://spdx.github.io/spdx-python-model/doc/stable/ -- latest release
# https://spdx.github.io/spdx-python-model/doc/dev/ -- from main branch (unreleased)
# https://spdx.github.io/spdx-python-model/doc/1.0/ -- for specific version (all 1.0.x will all published to this URL)
#
# Publish tutorials to
# https://spdx.github.io/spdx-python-model/tutorial/

name: Publish API docs

on:
  push:
    branches:
      - main
    paths:
      - '.github/workflows/docs.yaml'
      - 'gen/**'
      - 'src/**'
      - 'tutorial/**'
      - 'www/**'
      - 'README.md'
      - 'pyproject.toml'
  release:
    types: [published]
  workflow_dispatch:

jobs:
  deploy-docs:
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          fetch-depth: 0

      - name: Keep previously published versions
        run: |
          mkdir -p pages
          if git fetch origin gh-pages 2>/dev/null; then
            git archive origin/gh-pages | tar -x -C pages/
          fi

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.14"

      - name: Install dependencies
        run: pip install -e .
        # Use editable install (-e) to include the generated binding submodules
        # into the source tree so pdoc can see them.

      - name: Install pdoc
        run: pip install pdoc

      - name: Install nbconvert
        run: pip install nbconvert

      - name: Get version
        run: |
          if [[ "${{ github.event_name }}" == "release" ]]; then
            VERSION_RAW="${{ github.event.release.tag_name }}"
            VERSION="${VERSION_RAW#v}"
            echo "VERSION=$VERSION" >> $GITHUB_ENV
            echo "MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1-2)" >> $GITHUB_ENV
            echo "IS_RELEASE=true" >> $GITHUB_ENV
          else
            echo "VERSION=dev" >> $GITHUB_ENV
            echo "MAJOR_MINOR=dev" >> $GITHUB_ENV
            echo "IS_RELEASE=false" >> $GITHUB_ENV
          fi

      - name: Build landing page
        run: |
          if [[ -f www/index.html ]]; then
            cp www/index.html pages/index.html
          else
            echo '<meta http-equiv="refresh" content="0; url=doc/stable/" />' > pages/index.html
          fi

      - name: Build API docs
        run: |
          OUT="pages/doc/$MAJOR_MINOR"

          mkdir -p "$OUT"

          pdoc spdx_python_model \
            --logo "https://raw.githubusercontent.com/spdx/outreach/main/assets/SPDX_Logo/svg/SPDX%20logo%20color.svg" \
            --logo-link "/spdx-python-model/doc/$MAJOR_MINOR/" \
            --footer-text "spdx-python-model $VERSION" \
            -o "$OUT"

          # On release: update stable/ to match this major.minor.
          if [[ "$IS_RELEASE" == "true" ]]; then
            rm -rf pages/doc/stable
            cp -r "pages/doc/$MAJOR_MINOR" pages/doc/stable
          fi

          # /doc/ redirects to site root.
          mkdir -p pages/doc
          echo '<meta http-equiv="refresh" content="0; url=../" />' > pages/doc/index.html

      - name: Build tutorials
        run: |
          if [[ ! -d tutorial ]]; then
            exit 0
          fi

          mkdir -p pages/tutorial

          for nb in tutorial/*.ipynb; do
            jupyter nbconvert --to html --output-dir pages/tutorial "$nb"
          done

          # Generate /tutorial/ index listing all tutorials.
          if [[ ! -f tutorial/index.html ]]; then
            {
              echo '<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8">'
              echo '<meta name="viewport" content="width=device-width, initial-scale=1.0">'
              echo '<title>Tutorials - spdx-python-model</title>'
              echo '<style>body{font-family:system-ui,sans-serif;max-width:640px;margin:4rem auto;padding:0 1.5rem;color:#222}a{color:#0969da}li{margin-bottom:.5rem}</style>'
              echo '</head><body>'
              echo '<h1><a href="../">spdx-python-model</a></h1>'
              echo '<h2>Tutorials</h2><ul>'
              for html in pages/tutorial/*.html; do
                [[ "$(basename "$html")" == "index.html" ]] && continue
                name=$(basename "$html" .html)
                echo "<li><a href=\"$name.html\">$name</a> (<a href=\"https://github.com/spdx/spdx-python-model/blob/main/tutorial/$name.ipynb\">download .ipynb</a>)</li>"
              done
              echo '</ul></body></html>'
            } > pages/tutorial/index.html
          fi

          # File not found (404) page from repo.
          if [[ -f www/404.html ]]; then
            cp www/404.html pages/404.html
          fi

      - name: Setup Pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

      - name: Upload artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: pages

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0