Build & Deploy Documentation #1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # ============================================================================ | |
| # Build & deploy the DataLab documentation to GitHub Pages. | |
| # | |
| # Mirrors the local VS Code tasks `GitHub Pages: build` + `GitHub Pages: | |
| # upload` (see scripts/build_ghpages.bat + scripts/upload_ghpages.bat). | |
| # | |
| # Triggers: | |
| # * workflow_dispatch - manual run | |
| # * workflow_call - invoked by `release.yml` after a successful release | |
| # | |
| # Deployment target: | |
| # The current upload script pushes to the external repository | |
| # `DataLab-Platform/DataLab-Platform.github.io`. To keep parity, this | |
| # workflow pushes to the same repo using `peaceiris/actions-gh-pages`. | |
| # It requires the repository secret `GH_PAGES_TOKEN` (a fine-grained PAT | |
| # with write access to that external repo) OR `GH_PAGES_DEPLOY_KEY` | |
| # (an SSH deploy key configured on the external repo). At least one of | |
| # the two must be defined. | |
| # ============================================================================ | |
| name: Build & Deploy Documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| deploy: | |
| description: "Push the result to DataLab-Platform.github.io" | |
| required: true | |
| type: boolean | |
| default: true | |
| workflow_call: | |
| inputs: | |
| deploy: | |
| description: "Push the result to DataLab-Platform.github.io" | |
| required: false | |
| type: boolean | |
| default: true | |
| secrets: | |
| GH_PAGES_TOKEN: | |
| required: false | |
| GH_PAGES_DEPLOY_KEY: | |
| required: false | |
| permissions: | |
| contents: read | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| env: | |
| DISPLAY: ":99.0" | |
| QT_COLOR_MODE: light | |
| RELEASE: "1" | |
| UNATTENDED: "1" | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.11" | |
| cache: pip | |
| - name: Install system dependencies (Qt + Xvfb) | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y \ | |
| libxkbcommon-x11-0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \ | |
| libxcb-randr0 libxcb-render-util0 libxcb-xinerama0 libxcb-xfixes0 \ | |
| x11-utils xvfb | |
| /sbin/start-stop-daemon --start --quiet \ | |
| --pidfile /tmp/custom_xvfb_99.pid --make-pidfile --background \ | |
| --exec /usr/bin/Xvfb -- :99 -screen 0 1920x1200x24 -ac +extension GLX | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| python -m pip install --upgrade PythonQwt guidata PlotPy Sigima | |
| python -m pip install .[doc,qt] | |
| # sigima.proc.validation imports `_pytest` at module level (tech | |
| # debt); doc/update_validation_status.py needs it to be importable. | |
| python -m pip install pytest | |
| - name: Symlink Sigima sibling checkout for doc literalincludes | |
| run: | | |
| SITE=$(python -c "import sigima, os; print(os.path.dirname(os.path.dirname(sigima.__file__)))") | |
| ln -snf "$SITE" "$GITHUB_WORKSPACE/../Sigima" | |
| - name: Compile translations (UI + docs) | |
| run: | | |
| python -m sphinx build doc build/gettext -b gettext -W | |
| python -m sphinx_intl build -d doc/locale | |
| python -m guidata.utils.translations compile --name datalab --directory . | |
| - name: Generate doc assets | |
| run: | | |
| python -m guidata.utils.genreqs all | |
| python doc/update_validation_status.py | |
| - name: Build HTML documentation (fr + en) | |
| # NOTE: doc/update_screenshots.py is intentionally NOT run here — | |
| # screenshots in doc/images/ are committed assets (refreshed locally | |
| # by the maintainer via scripts/update_screenshots.bat). Sphinx | |
| # picks `foo.<lang>.png` automatically when present (via | |
| # `figure_language_filename` in doc/conf.py) and falls back to the | |
| # unsuffixed `foo.png` otherwise. See _build.yml for the same | |
| # rationale. | |
| run: | | |
| mkdir -p site | |
| # Loop variable is `LNG`, not `LANG`: `LANG` is the OS locale env var | |
| # read by Python's `locale.setlocale`, and setting it to a bare "fr" | |
| # / "en" makes Sphinx fail with `locale.Error: unsupported locale | |
| # setting` (see _build.yml for the same workaround). | |
| for LNG in fr en; do | |
| python -m sphinx -b html -D language=$LNG doc "site/$LNG" | |
| done | |
| # Top-level index redirecting to the English version. | |
| cat > site/index.html <<'EOF' | |
| <!doctype html> | |
| <meta http-equiv="refresh" content="0; url=./en/"> | |
| <link rel="canonical" href="./en/"> | |
| EOF | |
| - name: Upload built site as artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: datalab-docs-html | |
| path: site/ | |
| retention-days: 14 | |
| - name: Check for deployment credentials | |
| id: creds | |
| if: ${{ inputs.deploy }} | |
| env: | |
| TOKEN: ${{ secrets.GH_PAGES_TOKEN }} | |
| KEY: ${{ secrets.GH_PAGES_DEPLOY_KEY }} | |
| run: | | |
| if [ -n "$TOKEN" ]; then | |
| echo "method=token" >> "$GITHUB_OUTPUT" | |
| elif [ -n "$KEY" ]; then | |
| echo "method=ssh" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "::warning::No GH_PAGES_TOKEN or GH_PAGES_DEPLOY_KEY secret; skipping deployment." | |
| echo "method=none" >> "$GITHUB_OUTPUT" | |
| fi | |
| - name: Deploy to DataLab-Platform.github.io (via PAT) | |
| if: ${{ inputs.deploy && steps.creds.outputs.method == 'token' }} | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| personal_token: ${{ secrets.GH_PAGES_TOKEN }} | |
| external_repository: DataLab-Platform/DataLab-Platform.github.io | |
| publish_branch: main | |
| publish_dir: ./site | |
| keep_files: false | |
| commit_message: "Update documentation from ${{ github.repository }}@${{ github.sha }}" | |
| - name: Deploy to DataLab-Platform.github.io (via SSH deploy key) | |
| if: ${{ inputs.deploy && steps.creds.outputs.method == 'ssh' }} | |
| uses: peaceiris/actions-gh-pages@v4 | |
| with: | |
| deploy_key: ${{ secrets.GH_PAGES_DEPLOY_KEY }} | |
| external_repository: DataLab-Platform/DataLab-Platform.github.io | |
| publish_branch: main | |
| publish_dir: ./site | |
| keep_files: false | |
| commit_message: "Update documentation from ${{ github.repository }}@${{ github.sha }}" |