• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1name: Docs
2
3on:
4  workflow_dispatch:
5  #push:
6  #  branches:
7  #  - 'main'
8  #  - '3.11'
9  #  - '3.10'
10  #  - '3.9'
11  #  - '3.8'
12  #  - '3.7'
13  #  paths:
14  #  - 'Doc/**'
15  pull_request:
16    branches:
17    - 'main'
18    - '3.11'
19    - '3.10'
20    - '3.9'
21    - '3.8'
22    - '3.7'
23    paths:
24    - 'Doc/**'
25    - 'Misc/**'
26    - '.github/workflows/doc.yml'
27
28permissions:
29  contents: read
30
31concurrency:
32  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
33  cancel-in-progress: true
34
35jobs:
36  build_doc:
37    name: 'Docs'
38    runs-on: ubuntu-latest
39    timeout-minutes: 60
40    steps:
41    - uses: actions/checkout@v3
42    - name: Register Sphinx problem matcher
43      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
44    - name: 'Set up Python'
45      uses: actions/setup-python@v4
46      with:
47        python-version: '3'
48        cache: 'pip'
49        cache-dependency-path: 'Doc/requirements.txt'
50    - name: 'Install build dependencies'
51      run: make -C Doc/ venv
52    - name: 'Check documentation'
53      run: make -C Doc/ check
54    - name: 'Build HTML documentation'
55      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
56    - name: 'Upload'
57      uses: actions/upload-artifact@v3
58      with:
59        name: doc-html
60        path: Doc/build/html
61
62  # This build doesn't use problem matchers or check annotations
63  # It also does not run 'make check', as sphinx-lint is not installed into the
64  # environment.
65  build_doc_oldest_supported_sphinx:
66    name: 'Docs (Oldest Sphinx)'
67    runs-on: ubuntu-latest
68    timeout-minutes: 60
69    steps:
70    - uses: actions/checkout@v3
71    - name: 'Set up Python'
72      uses: actions/setup-python@v4
73      with:
74        python-version: '3.11'  # known to work with Sphinx 3.2
75        cache: 'pip'
76        cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
77    - name: 'Install build dependencies'
78      run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
79    - name: 'Build HTML documentation'
80      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
81
82  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
83  doctest:
84    name: 'Doctest'
85    runs-on: ubuntu-latest
86    timeout-minutes: 60
87    steps:
88    - uses: actions/checkout@v3
89    - name: Register Sphinx problem matcher
90      run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
91    - uses: actions/cache@v3
92      with:
93        path: ~/.cache/pip
94        key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }}
95        restore-keys: |
96          ubuntu-doc-
97    - name: 'Install Dependencies'
98      run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
99    - name: 'Configure CPython'
100      run: ./configure --with-pydebug
101    - name: 'Build CPython'
102      run: make -j4
103    - name: 'Install build dependencies'
104      run: make -C Doc/ PYTHON=../python venv
105    # Use "xvfb-run" since some doctest tests open GUI windows
106    - name: 'Run documentation doctest'
107      run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" doctest
108