Skip to content

refactor/emcomposition_field_handling #6299

refactor/emcomposition_field_handling

refactor/emcomposition_field_handling #6299

Workflow file for this run

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