Devel #6342
This file contains 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
| name: PsyNeuLink Docs CI | |
| on: | |
| push: | |
| branches-ignore: | |
| - 'dependabot/**' | |
| tags: | |
| - 'v*' | |
| pull_request: | |
| # run only the latest instance of this workflow job for the current branch/PR | |
| # cancel older runs | |
| # fall back to run id if not available (run id is unique -> no cancellations) | |
| concurrency: | |
| group: ci-${{ github.ref || github.run_id }}-${{ github.workflow }} | |
| cancel-in-progress: true | |
| jobs: | |
| docs-build: | |
| runs-on: ${{ matrix.os }} | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] | |
| os: [ubuntu-latest, macos-latest, windows-latest] | |
| pnl-version: ${{ (github.event_name == 'push') && fromJSON('["head"]') || fromJSON('["head", "base"]') }} | |
| exclude: | |
| - os: macos-latest | |
| pnl-version: 'base' | |
| - os: windows-latest | |
| pnl-version: 'base' | |
| - python-version: '3.7' | |
| pnl-version: 'base' | |
| - python-version: '3.8' | |
| pnl-version: 'base' | |
| - python-version: '3.9' | |
| pnl-version: 'base' | |
| - python-version: '3.10' | |
| pnl-version: 'base' | |
| - python-version: '3.12' | |
| pnl-version: 'base' | |
| # Python 3.7 x64 on macos-14 (arm64) images is broken [0] | |
| # and arm64 version is not available [1]. | |
| # Restrict python 3.7 macos runs to macos-13 | |
| # [0] https://github.com/actions/setup-python/issues/855 | |
| # [1] https://github.com/actions/setup-python/issues/856 | |
| - python-version: '3.7' | |
| os: macos-latest | |
| outputs: | |
| on_master: ${{ steps.on_master.outputs.on-branch }} | |
| steps: | |
| # Increased fetch-depth and tag checkout needed compared to pnl-ci.yml | |
| - name: Checkout sources | |
| uses: actions/checkout@v4 | |
| if: ${{ matrix.pnl-version == 'head' }} | |
| with: | |
| fetch-depth: 200 | |
| ref: ${{ github.ref }} | |
| - name: Checkout pull base | |
| uses: actions/checkout@v4 | |
| if: ${{ matrix.pnl-version == 'base' }} | |
| with: | |
| fetch-depth: 200 | |
| ref: ${{ github.base_ref }} | |
| - name: Checkout tags | |
| run: git fetch --tags origin master | |
| - name: Check if on master | |
| if: ${{ github.event_name == 'push' }} | |
| id: on_master | |
| uses: ./.github/actions/on-branch | |
| with: | |
| branch: master | |
| - name: Set up Python ${{ matrix.python-version }} | |
| uses: actions/setup-python@v5 | |
| with: | |
| # Block python3.7.17 on macos. see: | |
| # https://github.com/actions/setup-python/issues/682 | |
| python-version: ${{ (matrix.os == 'macos-latest' && matrix.python-version == '3.7') && '3.7.16' || matrix.python-version }} | |
| - name: Get pip cache location | |
| shell: bash | |
| id: pip_cache | |
| run: | | |
| python -m pip install -U pip | |
| python -m pip --version | |
| echo "pip_cache_dir=$(python -m pip cache dir)" | tee -a $GITHUB_OUTPUT | |
| - name: Wheels cache | |
| uses: actions/cache@v4 | |
| with: | |
| path: ${{ steps.pip_cache.outputs.pip_cache_dir }}/wheels | |
| key: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'doc_requirements.txt') }}-${{ github.sha }} | |
| restore-keys: ${{ runner.os }}-python-${{ matrix.python-version }}-pip-wheels-${{ hashFiles('requirements.txt', 'doc_requirements.txt') }} | |
| # We need to install all PNL deps since docs config imports psyneulink module | |
| - name: Install PNL package | |
| uses: ./.github/actions/install-pnl | |
| with: | |
| features: 'doc' | |
| - name: Add git tag | |
| # The generated docs include PNL version, | |
| # set it to a fixed value to prevent polluting the diff | |
| # This needs to be done after installing PNL | |
| # to not interfere with dependency resolution | |
| id: add_zero_tag | |
| if: github.event_name == 'pull_request' | |
| run: git tag --force 'v0.0.0.0' | |
| - name: Build Documentation | |
| run: make -C docs/ html -e SPHINXOPTS="-aE -j auto" | |
| - name: Remove git tag | |
| # The generated docs include PNL version, | |
| # A special tag was set to a fixed value | |
| # to prevent polluting the diff | |
| if: steps.add_zero_tag.outcome != 'skipped' | |
| run: git tag -d 'v0.0.0.0' | |
| - name: Upload Documentation | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: Documentation-${{matrix.pnl-version}}-${{ matrix.os }}-${{ matrix.python-version }} | |
| retention-days: 1 | |
| path: docs/build/html | |
| - name: Store PR number | |
| # The 'base' variant runs only on pull requests and has only one job | |
| if: ${{ matrix.pnl-version == 'base' }} | |
| run: echo ${{ github.event.pull_request.number }} > ./pr_number.txt | |
| - name: Upload PR number for other workflows | |
| # The 'base' variant runs only on pull requests and has only one job | |
| if: ${{ matrix.pnl-version == 'base' }} | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: pr_number | |
| path: ./pr_number.txt | |
| docs-deploy: | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| python-version: [3.11] | |
| os: [ubuntu-latest] | |
| runs-on: ${{ matrix.os }} | |
| permissions: | |
| contents: write | |
| needs: [docs-build] | |
| environment: github-pages | |
| if: github.event_name == 'push' && | |
| (github.ref == 'refs/heads/master' || | |
| github.ref == 'refs/heads/devel' || | |
| github.ref == 'refs/heads/docs' || | |
| (startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master')) | |
| ) | |
| steps: | |
| - name: Checkout docs | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: gh-pages | |
| - name: Download branch docs | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: Documentation-head-${{ matrix.os }}-${{ matrix.python-version }} | |
| path: _built_docs/${{ github.ref }} | |
| if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/devel' || github.ref == 'refs/heads/docs' | |
| - name: Update branch docs | |
| shell: bash | |
| run: | | |
| mkdir -p branch | |
| rm -rf "branch/${GITHUB_REF##*/}" | |
| # Remove '.doctrees' and move to correct location | |
| rm -rf "_built_docs/${GITHUB_REF}/.doctrees" | |
| mv -f "_built_docs/${GITHUB_REF}" branch/ | |
| if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/devel' || github.ref == 'refs/heads/docs' | |
| - name: Download main docs | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: Documentation-head-${{ matrix.os }}-${{ matrix.python-version }} | |
| # This overwrites files in current directory | |
| if: startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master') | |
| - name: Update main docs | |
| shell: bash | |
| run: | | |
| # Remove '.doctrees' | |
| rm -rf ".doctrees" | |
| if: startsWith(github.ref, 'refs/tags/') && contains(needs.*.outputs.on_master, 'master') | |
| - name: Commit docs changes | |
| shell: bash | |
| run: | | |
| # Commit changes to git | |
| git add . | |
| git config user.name "Documentation Bot" | |
| git config user.email "[email protected]" | |
| git commit -m "Docs changes for $GITHUB_REF $GITHUB_SHA" | |
| git push |