# Jobs:
# - "generate-docs"
#
#   This is job uses jsdoc library to generate a static site from the comments on the library code.
#
#   Once the static site is generated using the command 'yarn run build-jsdoc' from the 'mathtype-html-integration-devkit'
#   package, it runs some validations to the generated files at 'packages/devkit/out/' folder.
#
#   Validation consists on:
#    - The main index.html file is not empty.
#    - There are no broken links on the HTML files.
#
#   If validation passes the static site is published as an artifact called 'mathtype-html-integration-devkit-docs.zip'.

name: Generate and validate the jsdoc site

on:
  - push
  - workflow_dispatch

jobs:
  generate-docs:
    name: Generate and validate the jsdoc site
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # 01. install a specific version of Node using
      # https://github.com/actions/setup-node
      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ vars.NODE_VERSION }}

      # 02. Install html-integrations dependencies
      - name: Install dependencies
        run: |
          yarn install --frozen-lockfile

      # 03. Install mathtype-html-integration-devkit dependencies
      #     and run the jsdoc command to generate the static site.
      - name: Install depedencies and generate the jsdoc site
        run: |
          cd packages/devkit
          yarn install
          yarn run build-jsdoc

      # 04. Check if the generated documentation is empty.
      - name: Validate main index file is not empty
        id: check_files
        uses: andstor/file-existence-action@v1
        with:
          files: "packages/devkit/out/index.html"

      # 05. If the main index.html file is empty, raise an error to stop
      #     the workflow execution.
      - name: Errors if jsdoc site is empty
        if: steps.check_files.outputs.files_exists == 'false'
        # Only runs if the file does not exist
        uses: actions/github-script@v3
        with:
          script: |
            core.setFailed('jsdoc: main index file is empty')

      # 06. Upload the jsdoc site to github artifacts
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: mathtype-html-integration-devkit-docs
          path: |
            packages/devkit/out/
          if-no-files-found: error
