Documentation and small fix #406
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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/[email protected] | |
| with: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| BRANCH: gh-pages | |
| FOLDER: _build | |
| CLEAN: false |