Skip to content

Test

Test #387

Workflow file for this run

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@v3
# Update apt-get database
- name: Update apt-get database
run: sudo apt-get update
# Retrieve the opam cache with unique key
# A new cache is created/used if the `.opam` files changes or
# if we use another ocaml version
# This action only retrieve de .opam/ directory
- name: Retrieve opam cache
uses: actions/cache@v2
id: cache-opam
with:
path: ~/.opam
key: v1-${{ runner.os }}-alt-ergo-odoc-${{ env.OCAML_DEFAULT_VERSION }}-${{ hashFiles('*.opam') }}
# 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:
ocaml-compiler: ${{ env.OCAML_DEFAULT_VERSION }}
# Pin the packages, this is needed for opam depext
# remove this step when opam 2.1 will be used
- name: opam pin no action
run: opam pin add . --no-action
# Install external dependencies
# remove this step when opam 2.1 will be used
- name: opam install depext
run: opam depext alt-ergo-lib alt-ergo-parsers alt-ergo
# 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@v2
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@v3
# 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@v2
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@v2
with:
name: ocaml_doc
path: _build/odoc/dev
# Retrieve sphinx documentation artifact
- name: Download sphinx documentation
uses: actions/download-artifact@v2
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/[email protected]
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BRANCH: gh-pages
FOLDER: _build
CLEAN: false