docs.yml

name: Main Build and Deploy Docs

on:
  push:
    branches:
      - main
    paths:
    # run if any file in the docs folder is pushed
      - 'doc/**'    
      - '.github/workflows/docs.yml'    
  workflow_run:
    branches:
      - main
    workflows: ["Main Test and Release"]
    types:
      - completed

jobs:
  build_api_reference:
    # if not workflow_run, or if workflow was successful
    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
    
    runs-on: ubuntu-latest
    # available list of containers here:
    # https://hub.docker.com/r/unityci/editor/tags?page=1&ordering=last_updated&name=ubuntu-2020.1.17f1-base
    container: unityci/editor:ubuntu-2021.3.5f1-base-3.0.0

    steps:
      - name: Activate unity
        # exit code is 1 for manual activation
        continue-on-error: true
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE_2021_3_4 }}
        run: |          
          echo "$UNITY_LICENSE" | tr -d '\r' > UnityLicenseFile.ulf
          unity-editor -nographics -logFile /dev/stdout -manualLicenseFile UnityLicenseFile.ulf -quit

      - uses: actions/checkout@v4

      - name: Cache Library
        id: cache-library
        uses: actions/cache@v4
        with:
          path: Library
          key: Library-2021.3.5

      - name: Generate Solution
        run: unity-editor -nographics -logFile /dev/stdout -customBuildName Mirage -projectPath . -executeMethod GitTools.Solution.Sync -quit

      # unity 2020.3 outputs <ReferenceOutputAssembly>false</ReferenceOutputAssembly> on linux
      # this breaks references to other csproj for docfx and sonar.
      # This step is a work around for this so docfx runs in correctly
      # replacing false with true in ReferenceOutputAssembly
      - name: Fix Csproj
        run: sed -i 's/<ReferenceOutputAssembly>false<\/ReferenceOutputAssembly>/<ReferenceOutputAssembly>true<\/ReferenceOutputAssembly>/g' *.csproj

      - uses: nikeee/docfx-action@v1.0.0
        with:
          args: metadata --logLevel Warning doc/docfx.json

      # Build new api (will update cache when job finishes)
      - name: Convert metadata to markdown
        uses: fillefilip8/DocFxToMarkdown@1.4.0
        with:
          input-folder: doc/api
          output-folder: doc/docs/reference
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: metadata
          path: doc/docs/reference

  build_and_deploy:
    needs: build_api_reference
    
    runs-on: ubuntu-latest
    container: node:18
    steps:
      - uses: actions/checkout@v4

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: metadata
          path: doc/docs/reference

      # copies change log from mirage folder to docs
      - name: Copy ChangeLog
      # use cat and >> to append to placeholder file
        run: cat Assets/Mirage/CHANGELOG.md >> doc/docs/general/CHANGELOG.md
      - name: Escape HTML in ChangeLog
        run: sed -i 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g' doc/docs/general/CHANGELOG.md

      - name: Install dependencies
        working-directory: doc
        run: npm ci

      - name: Download EmbedCodeInMarkdown
        run: curl -LJO https://github.com/James-Frowen/EmbedCodeInMarkdown/releases/download/v1.0.3/EmbedCodeInMarkdown
      
      - name: Run EmbedCodeInMarkdown
        run: chmod +x ./EmbedCodeInMarkdown && ./EmbedCodeInMarkdown -docs="doc/docs/" -code="Assets/Mirage/Samples~/"

      - name: Build docusaurus
        working-directory: doc
        run: npm run build
        env:
          ORG_NAME: ${{ github.repository_owner }}
          REPO_NAME: ${{ github.event.repository.name }}

      - name: Publish docs
        uses: crazy-max/ghaction-github-pages@v4.0.0
        if: github.ref == 'refs/heads/main'
        with:
          keep_history: false
          jekyll: false
          # Build directory to deploy
          build_dir: doc/build
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}