build-doc.yml

name: Build the documentation

on:
  workflow_call:
    inputs:
      publish:
        required: false
        default: false
        type: boolean

jobs:
  #
  # Run shards documentation samples
  #
  docs-samples:
    # needs: Windows-64bits-Release
    name: Run Samples
    runs-on: windows-latest
    steps:
      - name: Checkout shards
        uses: actions/checkout@v3
        with:
          repository: fragcolor-xyz/shards
          fetch-depth: 1
      - name: Download shards
        uses: actions/download-artifact@v3
        with:
          name: shards-win64 Release
          path: docs/samples
      - name: Run samples
        env:
          SHARDS_GFX_BACKEND: D3D12
        shell: bash
        run: |
          cd docs/samples
          for i in $(find shards -name '*.shs' \( ! -path '*UI*' ! -path '*GFX*' ! -path '*Dialog*' \));
          do
            echo "Running sample $i";
            LOG_shards_FORMAT="[%l] %v" ./shards.exe new run-sample.shs file:"$i" looped:false 2>"$i.log";
          done
          for i in $(find shards -name '*.shs' \( -path '*UI*' -or -path '*GFX*' \));
          do
            echo "Running sample $i";
            LOG_shards_FORMAT="[%l] %v" ./shards.exe new run-sample.shs looped:true file:"$i" 2>"$i.log";
          done
      - name: Upload samples logs
        uses: actions/upload-artifact@v3
        with:
          name: samples-logs
          path: docs/samples/**/*.log
          if-no-files-found: error
          retention-days: 1

  #
  # Generate shards documentation (markdown)
  #
  docs-markdown:
    # needs: Windows-64bits-Debug
    name: Generate Markdown
    runs-on: windows-latest
    steps:
      - name: Checkout shards
        uses: actions/checkout@v3
        with:
          repository: fragcolor-xyz/shards
          fetch-depth: 1
      - name: Download shards
        uses: actions/download-artifact@v3
        with:
          name: shards-win64 Debug
          path: ./
      - name: Generate markdown
        shell: bash
        run: |
          ./shards.exe new docs/generate.shs
      - name: Upload markdown
        uses: actions/upload-artifact@v3
        with:
          name: docs-markdown
          path: |
            docs/docs/reference/shards/shards/**/*.md
            docs/docs/reference/shards/enums/**/*.md
            !docs/docs/reference/shards/enums/index.md
            !docs/docs/reference/shards/shards/index.md
            !docs/docs/reference/shards/shards/types.md
          if-no-files-found: error
          retention-days: 1

  #
  # Build documentation website
  #
  docs-website-build:
    needs: [docs-markdown, docs-samples]
    name: Build Website
    runs-on: ubuntu-latest
    steps:
      - name: Setup
        id: setup
        run: |
          echo "publish=${{ github.event.inputs.publish || inputs.publish }}" >> $GITHUB_OUTPUT
      - name: Checkout shards
        uses: actions/checkout@v3
        with:
          repository: fragcolor-xyz/shards
          fetch-depth: 1
          path: shards
      - name: Set up python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install mkdocs
        run: |
          pip install mkdocs-material
          pip install mkdocs-awesome-pages-plugin
          pip install mkdocs-macros-plugin
      - name: Download markdown
        uses: actions/download-artifact@v3
        with:
          name: docs-markdown
          path: shards/docs/docs/reference/shards
      - name: Download samples logs
        uses: actions/download-artifact@v3
        with:
          name: samples-logs
          path: shards/docs/samples
      - name: Checkout shards-examples
        uses: actions/checkout@v3
        with:
          repository: fragcolor-xyz/shards-examples
          fetch-depth: 1
          path: shards-examples
      - name: Link tutorials
        run: |
          # note: we link twice because some relative path (esp. include) might be incorrect
          cd shards/docs
          ln -s ../../shards-examples/tutorials/
          cd docs/learn/shards
          ln -s ../../../../../shards-examples/tutorials/
      - name: Step to start local HTTP server with Fragcolor docs
        run: |
          cd shards/docs && nohup mkdocs serve > nohup.out 2> nohup.err < /dev/null &
      - name: Wait for the docs website to start
        run: wget -qO- https://raw.githubusercontent.com/fragcolor-xyz/wait-for/WAIT_FOR_VERSION/wait-for | sh -s -- 127.0.0.1:8000 -- echo "Docs website is up"
        env:
          WAIT_FOR_VERSION: b90dabffc34fdae1f8bc84c4d442de60e5b47b35 # v2.2.4
      # - name: Step to check for broken links
      #   id: link-report
      #   uses: fragcolor-xyz/link-checker@0f3f6f07d7c0ab247d73468ae5c277c441c596a3
      #   with:
      #     url: "http://127.0.0.1:8000"
      #     blc_args: --recursive --verbose --follow true --exclude twitter.com
      #     allow_failures: false
      - name: Build website
        if: ${{ steps.setup.outputs.publish != 'true' }}
        run: |
          cd shards/docs
          mkdocs build
      - name: Build & publish website
        if: ${{ steps.setup.outputs.publish == 'true' }}
        run: |
          cd shards/docs
          git config --global user.name "Fragcolor bot"
          git config --global user.email "bot@fragcolor.xyz"
          mkdocs gh-deploy --force --message "Publish documentation from {sha}

          Using MkDocs {version}."
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: docs-website
          path: shards/docs/site/
          if-no-files-found: error
          retention-days: 1