Debian Codegraph @

.github/workflows/test-docs.yml

raw
1 # This is a GitHub workflow defining a set of jobs with a set of steps.
2 # ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
3 #
4 # This workflow validates the REST API definition and runs the pytest tests in
5 # the docs/ folder. This workflow does not build the documentation. That is
6 # instead tested via ReadTheDocs (https://readthedocs.org/projects/jupyterhub/).
7 #
8 name: Test docs
9
10 # The tests defined in docs/ are currently influenced by changes to _version.py
11 # and scopes.py.
12 on:
13 pull_request:
14 paths:
15 - "docs/**"
16 - "jupyterhub/_version.py"
17 - "jupyterhub/scopes.py"
18 - ".github/workflows/test-docs.yml"
19 push:
20 paths:
21 - "docs/**"
22 - "jupyterhub/_version.py"
23 - "jupyterhub/scopes.py"
24 - ".github/workflows/test-docs.yml"
25 branches-ignore:
26 - "dependabot/**"
27 - "pre-commit-ci-update-config"
28 tags:
29 - "**"
30 workflow_dispatch:
31
32 env:
33 # UTF-8 content may be interpreted as ascii and causes errors without this.
34 LANG: C.UTF-8
35 PYTEST_ADDOPTS: "--verbose --color=yes"
36
37 jobs:
38 validate-rest-api-definition:
39 runs-on: ubuntu-22.04
40 steps:
41 - uses: actions/checkout@v4
42
43 - uses: actions/setup-node@v4
44 with:
45 node-version: "20"
46 cache: npm
47
48 - name: Validate REST API definition
49 run: |
50 npx @redocly/cli lint
51
52 test-docs:
53 runs-on: ubuntu-22.04
54 steps:
55 - uses: actions/checkout@v4
56 with:
57 # make rediraffecheckdiff requires git history to compare current
58 # commit with the main branch and previous releases.
59 fetch-depth: 0
60
61 - uses: actions/setup-python@v5
62 with:
63 python-version: "3.11"
64 cache: pip
65 cache-dependency-path: |
66 requirements.txt
67 docs/requirements.txt
68
69 - name: Install requirements
70 run: |
71 pip install -e . -r docs/requirements.txt pytest
72
73 - name: pytest docs/
74 run: |
75 pytest docs/
76
77 # readthedocs doesn't halt on warnings,
78 # so raise any warnings here
79 - name: build docs
80 run: |
81 cd docs
82 make html
83
84 # Output broken and permanently redirected links in a readable format
85 - name: check links
86 uses: manics/action-sphinx-linkcheck-summary@main
87 with:
88 docs-dir: docs
89 build-dir: docs/_build
90
91 # make rediraffecheckdiff compares files for different changesets
92 # these diff targets aren't always available
93 # - compare with base ref (usually 'main', always on 'origin') for pull requests
94 # - only compare with tags when running against jupyterhub/jupyterhub
95 # to avoid errors on forks, which often lack tags
96 - name: check redirects for this PR
97 if: github.event_name == 'pull_request'
98 run: |
99 cd docs
100 export REDIRAFFE_BRANCH=origin/${{ github.base_ref }}
101 make rediraffecheckdiff
102
103 # this should check currently published 'stable' links for redirects
104 - name: check redirects since last release
105 if: github.repository == 'jupyterhub/jupyterhub'
106 run: |
107 cd docs
108 export REDIRAFFE_BRANCH=$(git describe --tags --abbrev=0)
109 make rediraffecheckdiff
110
111 # longer-term redirect check (fixed version) for older links
112 - name: check redirects since 3.0.0
113 if: github.repository == 'jupyterhub/jupyterhub'
114 run: |
115 cd docs
116 export REDIRAFFE_BRANCH=3.0.0
117 make rediraffecheckdiff