manual-rendering.yml

name: "Check NixOS Manual DocBook rendering against MD rendering"


on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    # Check every 24 hours
    - cron:  '0 0 * * *'

permissions:
  contents: read

jobs:
  check-rendering-equivalence:
    permissions:
      pull-requests: write  # for peter-evans/create-or-update-comment to create or update comment
    if: github.repository_owner == 'NixOS'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cachix/install-nix-action@v18
        with:
          # explicitly enable sandbox
          extra_nix_config: sandbox = true
      - uses: cachix/cachix-action@v12
        with:
          # This cache is for the nixpkgs repo checks and should not be trusted or used elsewhere.
          name: nixpkgs-ci
          signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'

      - name: Build DocBook and MD manuals
        run: |
          export NIX_PATH=nixpkgs=$(pwd)
          nix-build \
            --option restrict-eval true \
            -o docbook nixos/release.nix \
            -A manual.x86_64-linux
          nix-build \
            --option restrict-eval true \
            --arg configuration '{ documentation.nixos.options.allowDocBook = false; }' \
            -o md nixos/release.nix \
            -A manual.x86_64-linux

      - name: Compare DocBook and MD manuals
        id: check
        run: |
          export NIX_PATH=nixpkgs=$(pwd)
          .github/workflows/compare-manuals.sh \
            docbook/share/doc/nixos/options.html \
            md/share/doc/nixos/options.html

      # if the manual can't be built we don't want to notify anyone.
      # while this may temporarily hide rendering failures it will be a lot
      # less noisy until all nixpkgs pull requests have stopped using
      # docbook for option docs.
      - name: Comment on failure
        uses: peter-evans/create-or-update-comment@v2
        if: ${{ failure() && steps.check.conclusion == 'failure' }}
        with:
          issue-number: 189318
          body: |
            Markdown and DocBook manuals do not agree.

            Check https://github.com/NixOS/nixpkgs/actions/runs/${{ github.run_id }} for details.