docs.yaml

name: Docs

on:
    push:
        branches: [ "main" ]
    pull_request: null
    schedule:
        # Do not make it the first of the month and/or midnight since it is a very busy time
        - cron: "* 10 5 * *"

jobs:
    check-markdown:
        name: "Lint Markdown"
        runs-on: "ubuntu-latest"
        timeout-minutes: 1
        steps:
            -   name: "Checkout repository"
                uses: "actions/checkout@v4"

            -   name: "Check Markdown formatting"
                uses: "DavidAnson/markdownlint-cli2-action@v17.0.0"
                with:
                    globs: "*.md|docs/**/*.md"

    check-links:
        name: "Lint Links"
        runs-on: "ubuntu-latest"
        timeout-minutes: 1
        steps:
            -   name: "Checkout repository"
                uses: "actions/checkout@v4"

            -   name: "Restore lychee cache"
                uses: "actions/cache@v4"
                with:
                    path: ".lycheecache"
                    key: "cache-lychee-${{ github.sha }}"
                    restore-keys: cache-lychee-

            -   name: "Run Lychee"
                uses: "lycheeverse/lychee-action@v2.0.2"
                with:
                    # To keep in sync with Makefile#lychee
                    args: "--verbose --no-progress '*.md' 'docs/**/*.md' --cache --max-cache-age 1d ."
                    output: "${{ runner.temp }}/lychee/out.md"
                    fail: true

    # This is a "trick", a meta task which does not change, and we can use in
    # the protected branch rules as opposed to the individual tests which
    # may change regularly.
    validate-tests:
        name: "Docs Status"
        runs-on: "ubuntu-latest"
        needs:
            - "check-markdown"
            - "check-links"
        if: "always()"
        steps:
            - name: "Successful run"
              if: "${{ !(contains(needs.*.result, 'failure')) }}"
              run: "exit 0"

            - name: "Failing run"
              if: "${{ contains(needs.*.result, 'failure') }}"
              run: "exit 1"