build.yml

name: Build

on:
  push:
    branches:
      - main
    tags:
      - v**
  pull_request:
    branches:
      - main
  workflow_dispatch:
  schedule:
    - cron: '0 0 1,16 * *'

jobs:
  check_conventions:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - nox-sessions: 'black check_yaml check_json check_toml check_eof check_trailing_space check_lf'
            python-version: '3.x'
            node-version: '16.x'
          - nox-sessions: 'mypy pylint'
            python-version: '3.8'
          - nox-sessions: 'mypy pylint'
            python-version: '3.9'
          - nox-sessions: 'mypy pylint'
            python-version: '3.10'
          - nox-sessions: 'mypy pylint'
            python-version: '3.11'
          - nox-sessions: 'mypy pylint'
            python-version: '3.12'
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        if: matrix.node-version
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Setup Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        id: python-setup
        with:
          python-version: ${{ matrix.python-version }}
      - name: Cache node.js modules
        if: matrix.node-version
        uses: actions/cache@v4
        with:
          path: "**/node_modules"
          key: ${{ runner.os }}-${{ matrix.node-version }}-node_modules-${{ hashFiles('**/package-lock.json') }}
      - name: Cache nox environments
        uses: actions/cache@v4
        if: matrix.node-version
        with:
          path: |
            .nox/black
            .nox/check_*
          key: nox-${{ steps.python-setup.outputs.python-version }}-${{ hashFiles('requirements/dev-black.txt', 'requirements/dev-pre_commit_hooks.txt') }}
      - run: npm install
        if: matrix.node-version
      - run: npm run check
        if: matrix.node-version
      - run: pipx run nox -s ${{ matrix.nox-sessions }}

  build:
    needs: [check_conventions]
    strategy:
      fail-fast: false
      matrix:
        os:
          - 'ubuntu-latest'
          - 'windows-latest'
          - 'macos-latest'
        python-version:
          - '3.x'
        node-version:
          - '16.x'
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
        with:
          # Need full history to determine version number.
          fetch-depth: 0
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Cache node.js modules
        uses: actions/cache@v4
        with:
          path: "**/node_modules"
          key: ${{ runner.os }}-${{ matrix.node-version }}-node_modules-${{ hashFiles('**/package-lock.json') }}
      - run: npm install
      - name: Check for dirty working directory
        run: git diff --exit-code
      - run: python -m pip install nox
      - name: Build distributions
        id: dist
        run: nox -s dist
      - name: Install wheel
        run: python -m pip install "${{ steps.dist.outputs.wheel }}"
      - name: Upload wheels as artifacts
        uses: actions/upload-artifact@v4
        with:
          name: python-packages-${{ runner.os }}
          path: |
            dist/*.whl
            dist/*.tar.*
      - name: Setup Graphviz
        uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
        with:
          macos-skip-brew-update: 'true'
      - uses: actions/cache@v4
        with:
          path: ${{ github.workspace }}/theme_build_cache
          key: theme-build-cache-${{ runner.os }}-${{ github.run_id }}
      - name: Build docs
        env:
          SPHINX_IMMATERIAL_EXTERNAL_RESOURCE_CACHE_DIR: ${{ github.workspace }}/theme_build_cache
        run: nox -s docs
      - name: Upload doc builds as artifacts
        uses: actions/upload-artifact@v4
        with:
          name: doc-builds-${{ runner.os }}
          path: docs/_build/

  test:
    needs: [check_conventions, build]
    strategy:
      fail-fast: false
      matrix:
        os:
          - 'ubuntu-latest'
          - 'windows-latest'
          - 'macos-latest'
        python-version:
          - '3.8'
          - '3.9'
          - '3.10'
          - '3.11'
          - '3.12'
        sphinx-version:
          - 'sphinx4'
          - 'sphinx5'
          - 'sphinx6'
          - 'sphinx7'
        node-version:
          - '16.x'
        exclude:
          - python-version: '3.8'
            sphinx-version: 'sphinx7'
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - name: Cache node.js modules
        uses: actions/cache@v4
        with:
          path: "**/node_modules"
          key: ${{ runner.os }}-${{ matrix.node-version }}-node_modules-${{ hashFiles('**/package-lock.json') }}
      - run: npm install
      - name: Build CSS and JS bundles
        run: npm run build
      - name: Setup Graphviz
        uses: ts-graphviz/setup-graphviz@b1de5da23ed0a6d14e0aeee8ed52fdd87af2363c # v2.0.2
        with:
          macos-skip-brew-update: 'true'
      - uses: actions/cache/restore@v4
        with:
          path: ${{ github.workspace }}/theme_build_cache
          key: theme-build-cache-${{ runner.os }}-${{ github.run_id }}
      - name: Run Python tests
        env:
          SPHINX_IMMATERIAL_EXTERNAL_RESOURCE_CACHE_DIR: ${{ github.workspace }}/theme_build_cache
          COVERAGE_FILE: .coverage.${{ github.run_id }}.${{ github.run_attempt }}.${{ runner.os }}.${{ matrix.python-version }}.${{ matrix.sphinx-version }}
        # `coverage run` cmd adds the working dir to python path, so no need to install pkg here
        run: pipx run nox -s "tests-${{ matrix.python-version }}(${{ matrix.sphinx-version }})"
      - name: Upload coverage data
        uses: actions/upload-artifact@v4
        with:
          name: coverage-data-${{ runner.os }}-py${{ matrix.python-version }}-${{ matrix.sphinx-version }}
          path: .coverage*

  coverage-report:
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download all artifacts
        uses: actions/download-artifact@v4
        with:
          path: ci-artifacts
          pattern: coverage-data-*
      - run: mv ci-artifacts/**/.coverage* ./
      - name: Setup python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - name: Create coverage report
        run: pipx run nox -s coverage
      - name: Upload comprehensive coverage HTML report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: htmlcov/
      - name: Post coverage summary
        run: cat .coverage_.md >> $GITHUB_STEP_SUMMARY

  compare-wheels:
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - name: Download Linux package
        uses: actions/download-artifact@v4
        with:
          name: python-packages-Linux
          path: dist-Linux
      - name: Download macOS package
        uses: actions/download-artifact@v4
        with:
          name: python-packages-macOS
          path: dist-macOS
      - name: Download Windows package
        uses: actions/download-artifact@v4
        with:
          name: python-packages-Windows
          path: dist-Windows
      - name: Unzip wheels
        run: |
          for os in Linux Windows macOS; do
            unzip -d pkg-$os dist-$os/*.whl
          done
      - name: Compare macOS wheel to Linux wheel
        run: diff -ur --color=always pkg-Linux pkg-macOS
      - name: Compare Windows wheel to Linux wheel
        run: diff -ur --color=always pkg-Windows pkg-Windows

  python-publish-package:
    # Only publish package on push to tag or default branch.
    if: ${{ github.event_name == 'push' && github.repository == 'jbms/sphinx-immaterial' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main') }}
    runs-on: ubuntu-latest
    needs: [build, coverage-report]
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: python-packages-Linux
          path: dist
      - name: Publish to PyPI (test server)
        uses: pypa/gh-action-pypi-publish@ec4db0b4ddc65acdf4bff5fa45ac92d78b56bdf0 # v1.9.0
        continue-on-error: true
        with:
          user: __token__
          password: ${{ secrets.pypi_test_token }}
          repository-url: https://test.pypi.org/legacy/
        if: ${{ ! startsWith(github.ref, 'refs/tags/v') }}
      - name: Publish to PyPI (main server)
        uses: pypa/gh-action-pypi-publish@ec4db0b4ddc65acdf4bff5fa45ac92d78b56bdf0 # v1.9.0
        with:
          user: __token__
          password: ${{ secrets.pypi_token }}
        if: ${{ startsWith(github.ref, 'refs/tags/v') }}
      - uses: actions/checkout@v4
        if: ${{ startsWith(github.ref, 'refs/tags/v') }}
      - name: Create a Github Release
        if: ${{ startsWith(github.ref, 'refs/tags/v') }}
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create ${{ github.ref_name }} --generate-notes
      - name: Download docs artifact
        uses: actions/download-artifact@v4
        with:
          name: doc-builds-${{ runner.os }}
          path: docs/_build/html
      - name: Download coverage report artifact
        uses: actions/download-artifact@v4
        with:
          name: coverage-report
          path: docs/_build/html/coverage_report/
      - name: upload docs to github pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # pinned to v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html