docs_build.yml

name: Docs Build
on:
  workflow_dispatch:
    inputs:
      version: { type: string, required: false, description: "The version to build (used in git and pypi). git-tag='v{version}-docs'.  If not specified then use master and wheel from the last successful build."}
      latest: { type: boolean, required: false, description: Alias this version as the 'latest' stable docs.  This should be set for the latest stable release.}
      deploy: { type: boolean, required: false, description: Push the built docs to the docs-pages branch on github.}
      
jobs:
  docs_build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v3.3.0
        with:
          ref: ${{inputs.version && format('v{0}-docs', inputs.version) || 'master'}}

      - name: Fetch docs-pages branch
        if: ${{inputs.deploy}}
        run: git fetch origin docs-pages --depth=1

      - name: Detect runner Python implementation
        if: ${{!inputs.version}}
        run: |
          python3 -c 'import platform
          prefix = {"CPython": "cp", "PyPy": "pp"}[platform.python_implementation()]
          v = platform.python_version_tuple()
          print(f"PY_IMPL={prefix}{v[0]}{v[1]}")' | tee -a $GITHUB_ENV
  
      - id: download-wheel-artifact
        name: Download wheel artifact from last successful build
        if: ${{!inputs.version}}
        uses: dawidd6/action-download-artifact@v2.28.0
        with:
          name: wheel-${{env.PY_IMPL}}-manylinux_x86_64
          workflow: build.yml
          workflow_conclusion: success
          branch: master

      - name: Install documentation dependencies (including ArcticDB)
        run: |
          set -x
          pip3 install mkdocs-material mkdocs-jupyter mkdocstrings[python] black pybind11-stubgen mike ${{inputs.version && format('arcticdb=={0}',inputs.version) || 'arcticdb-*.whl'}}

      - name: Stubfile generation for arcticdb_ext
        run: |
          set -x
          cd docs/mkdocs
          # stubfiles will be generated into docs/mkdocs/arcticdb_ext and so imported as arcticdb_ext by mkdocs when it builds
          # FIXME --ignore-all-errors may mask new errors and should be removed when we are compliant
          pybind11-stubgen arcticdb_ext.version_store --ignore-all-errors -o .

      - name: List docs versions before deploy
        run: |
          set -x
          cd docs/mkdocs
          mike list

      - name: Versioned mkDocs build 
        run: |
          set -x
          cd docs/mkdocs
          # mike needs a git user to be set
          git config --global user.name "${GITHUB_ACTOR}"
          git config --global user.email "${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com"
          git_hash=$(git rev-parse --short HEAD)
          mike deploy ${{inputs.version || 'dev'}} ${{inputs.latest && 'latest' || ''}} --update-aliases --branch docs-pages ${{inputs.deploy && '--push' || ''}} --message "Deploying docs: ${{inputs.version || 'dev'}} $git_hash ${{inputs.latest && '[latest]' || ''}}"
          mike set-default latest --branch docs-pages ${{inputs.deploy && '--push' || ''}}

      - name: List docs versions after deploy
        run: |
          set -x
          cd docs/mkdocs
          mike list