Update sphinx doc 2.6.0 #3024
Workflow file for this run
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: | |
| 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 |