documentation.yml

name: Documentation

on:
  push:
    branches-ignore:
      - coverity_scan
      - run-fuzzer**
      - debug-fuzzer-**
    paths:
      - '.github/workflows/documentation.yml'
      - 'doc/**'
      - 'man/**'
      - 'raddb/**'
      - 'share/**'
  pull_request:
    paths:
      - '.github/workflows/documentation.yml'
      - 'doc/**'
      - 'man/**'
      - 'raddb/**'
      - 'share/**'

jobs:
  build-docs:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: true

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Install common build dependencies
      run: |
        sudo apt-get install -y --no-install-recommends \
        asciidoctor \
        doxygen \
        graphviz

    - name: Install Antora
      run: |
        sudo npm i -g @antora/cli@3.1 @antora/site-generator@3.1;

    - name: Show versions
      run: |
        make --version
        echo -n "doxygen " ; doxygen --version
        asciidoctor --version
        echo -n "npm " ; npm --version
        echo -n "node " ; node --version
        antora --version

    - name: Build doxygen content
      run: |
         cd doc/doxygen;
         doxygen Doxyfile;

    - name: Build Antora docsite
      run: |
        LATEST_RELEASE=$(git tag -l 'release_3_2*' | sort | tail -1 | sed -e 's/release_//' -e 's/_/\./g')
        sed -e "s/%LATEST%/$LATEST_RELEASE/" doc/antora/main-site.yml.in > main-site.yml
        antora --to-dir build/docsite main-site.yml

    - name: Tar output files
      run: tar -czf site.tgz doc/doxygen/html build/docsite

    - name: Store output
      uses: actions/upload-artifact@v4
      with:
        name: compiled-docs
        path: site.tgz
        retention-days: 1

  # Actual deployment to GitHub Pages is only on pushes to the head of the master branch
  deploy-doxygen-docs:
    if: ( github.repository_owner == 'FreeRADIUS' ) && ( github.ref == 'refs/heads/master' ) && ( github.event_name == 'push' )

    needs:
      - build-docs

    runs-on: ubuntu-latest

    strategy:
      fail-fast: true

    # Permissions needed to deploy on GitHub Pages
    permissions:
      contents: read
      pages: write
      id-token: write

    # Ensure only one job is attempting to update GitHub Pages
    concurrency:
      group: "documentation"
      cancel-in-progress: true

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
    - name: Retrieve output
      uses: actions/download-artifact@v4
      with:
        name: compiled-docs

    - name: Extract sites
      run: tar -zxf site.tgz

    - name: Setup Pages
      uses: actions/configure-pages@v3

    - name: Upload Doxygen content
      uses: actions/upload-pages-artifact@v3
      with:
        path: 'doc/doxygen/html'

    - name: Deploy doxygen content to GitHub pages
      id: deployment
      uses: actions/deploy-pages@v4

  deploy-antora-docs:
    if: ( github.repository_owner == 'FreeRADIUS' ) && ( github.ref == 'refs/heads/master' ) && ( github.event_name == 'push' )

    needs:
      - build-docs

    runs-on: ubuntu-latest

    strategy:
      fail-fast: true

    # Ensure only one job is attempting to update the docs repo
    concurrency:
      group: "antora-documentation"
      cancel-in-progress: true

    steps:
    - name: Setup SSH for git access
      uses: shimataro/ssh-key-action@v2
      with:
        key: ${{ secrets.NR_GIT_SSH_GITHUBACTIONS_KEY }}
        name: id_rsa-git
        known_hosts: ${{ secrets.NR_GIT_SSH_KNOWN_HOSTS }}
        config: |
          Host git.networkradius.com
            User git
            IdentityFile ~/.ssh/id_rsa-git

    - name: Retrieve output
      uses: actions/download-artifact@v4
      with:
        name: compiled-docs

    - name: Extract sites
      run: tar -zxf site.tgz

    - name: Checkout doc repository
      run: |
        git config --global user.email "git@github.com"
        git config --global user.name "Github Actions"
        git clone -b master git@git.networkradius.com:www.freeradius.org-docs www.freeradius.org-docs

    - name: Remove existing web site from repo
      run: |
        cd www.freeradius.org-docs
        git ls-files -moc | grep -v ._antora_docs_repo | xargs -r git rm

    - name: Copy new web site to repo
      run: |
        rsync -av build/docsite/ www.freeradius.org-docs/

    - name: Commit new web site files
      run: |
        cd www.freeradius.org-docs
        rm -f sitemap*.xml
        git ls-files -o | xargs -r git add
        git commit -q -m "Github Actions auto commit $(date)" || true

    - name: Push doc repository
      run: |
        cd www.freeradius.org-docs
        git push origin