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, pull_request]

env:
  OCAML_DEFAULT_VERSION: 4.10.0
  # 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@v2
        with:
          allow-prerelease-opam: true
          ocaml-compiler: ${{ env.OCAML_DEFAULT_VERSION }}
          dune-cache: true

      # 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
      # if: steps.cache-opam.outputs.cache-hit != 'true'

      # Try to upgrade installed packages and fix dependencies if needed,
      # when the cache is retrieved
      # - run: opam upgrade --fixup
      #  if: steps.cache-opam.outputs.cache-hit == 'true'

      # Make the documentation
      - name: Make OCaml documentation
        run: opam exec -- make odoc

      # Create and upload an artifact `ocaml_doc` that contains the ocaml
      # documentation in html format.
      # This is only done if this workflow is triggered in a PR or on the
      # following branches : next, main
      - name: Upload ocaml documentation
        uses: actions/upload-artifact@v4
        if: github.event_name == 'pull_request' || github.ref == 'refs/heads/next' || github.ref == 'refs/heads/main'
        with:
          name: ocaml_doc
          path: _build/default/_doc/_html/


  # On PR, or push on next/main, build the sphinx general documentation
  # If this build fails, the documentation workflow stops
  # If it succeeds, an artifact is made with the generated documentation
  # This artifact is used in the deploying job
  sphinx_docs:
    name: Sphinx documentation

    # We only run this if the ocaml documentation build is successful
    needs: ocaml_docs

    # Sphinx documentation is only builded if a PR is open or when it's
    # pushed on next or main
    if: github.event_name == 'pull_request' || github.ref == 'refs/heads/next' || github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest

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

      # 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 -b html . _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


  # For every push on main, retrieve ocaml and sphinx documentation
  # and publish them on gh-pages branch
  deploy_docs:
    name: Deploy documentation

    if: github.ref == 'refs/heads/main'

    needs:
      - ocaml_docs
      - sphinx_docs

    runs-on: ubuntu-latest
    steps:
      # Retrieve ocaml documentation artifact
      - name: Download ocaml documentation
        uses: actions/download-artifact@v4
        with:
          name: ocaml_doc
          path: _build/odoc/dev

      # Retrieve sphinx documentation artifact
      - name: Download sphinx documentation
        uses: actions/download-artifact@v4
        with:
          name: sphinx_doc
          path: _build

      - name: Add files to bypass nojekyll
        run: |
          touch _build/.nojekyll
          touch _build/odoc/.nojekyll
          touch _build/odoc/dev/.nojekyll

      # Deploy files contain in _build directory on gh-pages branch
      - 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