mirror of https://github.com/python/cpython
109 lines
4.1 KiB
YAML
109 lines
4.1 KiB
YAML
name: Docs
|
|
|
|
on:
|
|
workflow_call:
|
|
workflow_dispatch:
|
|
|
|
permissions:
|
|
contents: read
|
|
|
|
concurrency:
|
|
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
|
|
cancel-in-progress: true
|
|
|
|
jobs:
|
|
build_doc:
|
|
name: 'Docs'
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 60
|
|
env:
|
|
branch_base: 'origin/${{ github.event.pull_request.base.ref }}'
|
|
branch_pr: 'origin/${{ github.event.pull_request.head.ref }}'
|
|
refspec_base: '+${{ github.event.pull_request.base.sha }}:remotes/origin/${{ github.event.pull_request.base.ref }}'
|
|
refspec_pr: '+${{ github.event.pull_request.head.sha }}:remotes/origin/${{ github.event.pull_request.head.ref }}'
|
|
steps:
|
|
- name: 'Check out latest PR branch commit'
|
|
uses: actions/checkout@v4
|
|
with:
|
|
ref: ${{ github.event.pull_request.head.sha }}
|
|
# Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
|
|
- name: 'Fetch commits to get branch diff'
|
|
run: |
|
|
# Fetch enough history to find a common ancestor commit (aka merge-base):
|
|
git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \
|
|
--no-tags --prune --no-recurse-submodules
|
|
|
|
# This should get the oldest commit in the local fetched history (which may not be the commit the PR branched from):
|
|
COMMON_ANCESTOR=$( git rev-list --first-parent --max-parents=0 --max-count=1 ${{ env.branch_pr }} )
|
|
DATE=$( git log --date=iso8601 --format=%cd "${COMMON_ANCESTOR}" )
|
|
|
|
# Get all commits since that commit date from the base branch (eg: master or main):
|
|
git fetch origin ${{ env.refspec_base }} --shallow-since="${DATE}" \
|
|
--no-tags --prune --no-recurse-submodules
|
|
- name: 'Set up Python'
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3'
|
|
cache: 'pip'
|
|
cache-dependency-path: 'Doc/requirements.txt'
|
|
- name: 'Install build dependencies'
|
|
run: make -C Doc/ venv
|
|
|
|
# To annotate PRs with Sphinx nitpicks (missing references)
|
|
- name: 'Build HTML documentation'
|
|
continue-on-error: true
|
|
run: |
|
|
set -Eeuo pipefail
|
|
# Build docs with the '-n' (nit-picky) option; write warnings to file
|
|
make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going -w sphinx-warnings.txt" html
|
|
- name: 'Check warnings'
|
|
if: github.event_name == 'pull_request'
|
|
run: |
|
|
python Doc/tools/check-warnings.py \
|
|
--annotate-diff '${{ env.branch_base }}' '${{ env.branch_pr }}' \
|
|
--fail-if-regression \
|
|
--fail-if-improved
|
|
|
|
# This build doesn't use problem matchers or check annotations
|
|
build_doc_oldest_supported_sphinx:
|
|
name: 'Docs (Oldest Sphinx)'
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 60
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- name: 'Set up Python'
|
|
uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.11' # known to work with Sphinx 4.2
|
|
cache: 'pip'
|
|
cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
|
|
- name: 'Install build dependencies'
|
|
run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
|
|
- name: 'Build HTML documentation'
|
|
run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
|
|
|
|
# Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
|
|
doctest:
|
|
name: 'Doctest'
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 60
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: actions/cache@v3
|
|
with:
|
|
path: ~/.cache/pip
|
|
key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }}
|
|
restore-keys: |
|
|
ubuntu-doc-
|
|
- name: 'Install Dependencies'
|
|
run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
|
|
- name: 'Configure CPython'
|
|
run: ./configure --with-pydebug
|
|
- name: 'Build CPython'
|
|
run: make -j4
|
|
- name: 'Install build dependencies'
|
|
run: make -C Doc/ PYTHON=../python venv
|
|
# Use "xvfb-run" since some doctest tests open GUI windows
|
|
- name: 'Run documentation doctest'
|
|
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="-W --keep-going" doctest
|