test-docs.yml

# This is a GitHub workflow defining a set of jobs with a set of steps.
# ref: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions
#
# This workflow validates the REST API definition and runs the pytest tests in
# the docs/ folder. This workflow does not build the documentation. That is
# instead tested via ReadTheDocs (https://readthedocs.org/projects/jupyterhub/).
#
name: Test docs

# The tests defined in docs/ are currently influenced by changes to _version.py
# and scopes.py.
on:
  pull_request:
    paths:
      - "docs/**"
      - "jupyterhub/_version.py"
      - "jupyterhub/scopes.py"
      - ".github/workflows/test-docs.yml"
  push:
    paths:
      - "docs/**"
      - "jupyterhub/_version.py"
      - "jupyterhub/scopes.py"
      - ".github/workflows/test-docs.yml"
    branches-ignore:
      - "dependabot/**"
      - "pre-commit-ci-update-config"
    tags:
      - "**"
  workflow_dispatch:

env:
  # UTF-8 content may be interpreted as ascii and causes errors without this.
  LANG: C.UTF-8
  PYTEST_ADDOPTS: "--verbose --color=yes"

jobs:
  validate-rest-api-definition:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4

      - name: Validate REST API definition
        uses: char0n/swagger-editor-validate@v1.3.2
        with:
          definition-file: docs/source/_static/rest-api.yml

  test-docs:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v4
        with:
          # make rediraffecheckdiff requires git history to compare current
          # commit with the main branch and previous releases.
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.9"

      - name: Install requirements
        run: |
          pip install -r docs/requirements.txt pytest

      - name: pytest docs/
        run: |
          pytest docs/

      # readthedocs doesn't halt on warnings,
      # so raise any warnings here
      - name: build docs
        run: |
          cd docs
          make html

      - name: check links
        run: |
          cd docs
          make linkcheck

      # make rediraffecheckdiff compares files for different changesets
      # these diff targets aren't always available
      # - compare with base ref (usually 'main', always on 'origin') for pull requests
      # - only compare with tags when running against jupyterhub/jupyterhub
      #   to avoid errors on forks, which often lack tags
      - name: check redirects for this PR
        if: github.event_name == 'pull_request'
        run: |
          cd docs
          export REDIRAFFE_BRANCH=origin/${{ github.base_ref }}
          make rediraffecheckdiff

      # this should check currently published 'stable' links for redirects
      - name: check redirects since last release
        if: github.repository == 'jupyterhub/jupyterhub'
        run: |
          cd docs
          export REDIRAFFE_BRANCH=$(git describe --tags --abbrev=0)
          make rediraffecheckdiff

      # longer-term redirect check (fixed version) for older links
      - name: check redirects since 3.0.0
        if: github.repository == 'jupyterhub/jupyterhub'
        run: |
          cd docs
          export REDIRAFFE_BRANCH=3.0.0
          make rediraffecheckdiff