documentation.yml

name: Documentation

# This workflow is divided in 3 jobs, ocaml_docs, sphinx_docs, deploy_docs.
# - The ocaml_docs build the ocaml documentation, it runs for every push,
# if it fails no more work is done
# - The sphinx_docs job build the sphinx documentation, it runs only if a PR
# is open. if it fails no more work is done
# - deploy_docs only run on the next branch when code is pushed. It retrieve
# the ocaml and sphinx documentation and deploy them on the gh-pages branch

on:
  push:
    tags:
      - "v*.*.*"
    branches:
      - next
      - main
  pull_request:

env:
  OCAML_DEFAULT_VERSION: 4.14.2
  # Add OPAMYES=true to the environment, this is usefill to replace `-y` option
  # in any opam call
  OPAMYES: true

jobs:
  # For any push and PR, build the documentation from the ocaml comments
  # If this build fails, the documentation workflow stops
  # If it succeeds, an artifact is made with the generated documentation
  # (html format only). This artifact is used in the deploying job
  ocaml_docs:
    name: OCaml documentation

    runs-on: ubuntu-latest

    env:
      OPAMWITHDOC: true

    steps:
      # Checkout the code of the current branch
      - name: Checkout code
        uses: actions/checkout@v4

      # Update apt-get database
      - name: Update apt-get database
        run: sudo apt-get update

      # Get an OCaml environment with opam installed and the proper ocaml version
      # opam will used opam cache environment if retrieved
      - name: Use OCaml ${{ env.OCAML_DEFAULT_VERSION }}
        uses: ocaml/setup-ocaml@v3
        with:
          ocaml-compiler: ${{ env.OCAML_DEFAULT_VERSION }}
          # https://github.com/ocaml/dune/issues/7720
          dune-cache: false

      - name: Retrieve annotated tags for dune
        run: git fetch --tags --force


      # Install dependencies if the cache is not retrieved
      # odoc is installed as deps with { with-doc } in opam files
      - name: opam install deps
        run: opam exec -- make deps

      - name: Perform version substitution
        run: opam exec -- dune subst

      # Make the documentation
      - name: Make OCaml documentation
        run: opam exec -- dune build @doc

      # Create and upload an artifact `ocaml_doc` that contains the ocaml
      # documentation in html format.
      - name: Upload ocaml documentation
        uses: actions/upload-artifact@v4
        with:
          name: ocaml_doc
          path: _build/default/_doc/_html/

  sphinx_docs:
    name: Sphinx documentation
    runs-on: ubuntu-latest

    outputs:
      version-name: ${{ steps.version-name.outputs.target }}

    steps:
      # Checkout the code of the current branch
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Determine version name
        id: version-name
        run: |
          echo "target=${GITHUB_REF#*/*/}" >> $GITHUB_OUTPUT

      # Build the sphinx documentation
      # and automatically print any error or warning
      - name: Build sphinx documentation
        uses: ammaraskar/sphinx-action@master
        with:
          docs-folder: "docs/sphinx_docs/"
          build-command: >
            sphinx-build -W -b html
              -A current_version=${{ steps.version-name.outputs.target }}
              . _build

      # Create and upload an artifact `sphinx_doc` that contains the sphinx
      # documentation in html format.
      - name: Upload sphinx documentation
        uses: actions/upload-artifact@v4
        with:
          name: sphinx_doc
          path: docs/sphinx_docs/_build

  deploy_docs:
    name: Deploy documentation
    permissions:
      contents: write

    if: ${{ github.event_name == 'push' }}

    needs:
      - ocaml_docs
      - sphinx_docs

    runs-on: ubuntu-latest
    steps:
      - name: Download sphinx documentation
        uses: actions/download-artifact@v4
        with:
          name: sphinx_doc
          path: _build/${{ needs.sphinx_docs.outputs.version-name }}

      - name: Download ocaml documentation
        uses: actions/download-artifact@v4
        with:
          name: ocaml_doc
          path: _build/${{ needs.sphinx_docs.outputs.version-name }}/API

      - name: deploy-doc
        uses: JamesIves/github-pages-deploy-action@3.6.2
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: _build
          CLEAN: false

  update_versions:
    name: Update documentation versions
    permissions:
      contents: write

    needs: deploy_docs
    runs-on: ubuntu-latest

    if: ${{ github.event_name == 'push' }}

    steps:
      - name: Checkout documentation
        uses: actions/checkout@v4
        with:
          ref: gh-pages

      - name: Update latest version
        if: startsWith(github.ref, 'refs/tags/')
        run: |
          ln -nsf ${{ needs.sphinx_docs.outputs.version-name }} latest

      - name: Write versions to JSON file
        run: |
          rm -f versions.json
          echo -n '[' >versions.json
          PREFIX=''
          for version in $(ls -d */ | sort -n); do
            echo -n "$PREFIX" >>versions.json
            PREFIX=','
            echo -n '{"url": "/alt-ergo/'$version'", "slug": "'${version%/}'"}' >>versions.json
          done
          echo -n ']' >>versions.json

      - name: Push new versions
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add versions.json
          git commit -m 'Update versions.json' || exit 0
          git push