typo #210
This file contains hidden or 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 | |
| - multidoc | |
| 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@v3 | |
| with: | |
| ocaml-compiler: ${{ env.OCAML_DEFAULT_VERSION }} | |
| # https://github.com/ocaml/dune/issues/7720 | |
| dune-cache: false | |
| # 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 | |
| # 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. | |
| - 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 -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 | |
| # For every push on main, retrieve ocaml and sphinx documentation | |
| # and publish them on gh-pages branch | |
| deploy_docs: | |
| name: Deploy documentation | |
| permissions: | |
| contents: write | |
| if: ${{ github.event_name == 'push' }} | |
| needs: | |
| - ocaml_docs | |
| - sphinx_docs | |
| runs-on: ubuntu-latest | |
| steps: | |
| # Retrieve sphinx documentation artifact | |
| - name: Download sphinx documentation | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: sphinx_doc | |
| path: _build/${{ needs.sphinx_docs.outputs.version-name }} | |
| # Retrieve ocaml documentation artifact | |
| - name: Download ocaml documentation | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: ocaml_doc | |
| path: _build/${{ needs.sphinx_docs.outputs.version-name }}/API | |
| - name: Add files to bypass nojekyll | |
| run: | | |
| touch _build/${{ needs.sphinx_docs.outputs.version-name }}/.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 | |
| 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: Write versions to JSON file | |
| run: | | |
| rm -f versions.json | |
| echo '[' >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: Write versions to index.md | |
| run: | | |
| rm -f index.md | |
| echo '# Alt-Ergo' >index.md | |
| echo 'Select the documentation for your version:' >>index.md | |
| for version in $(ls -d */ | sort -n); do | |
| echo " - [${version%/}]($version)" >>index.md | |
| done | |
| - name: Push new versions | |
| run: | | |
| git config user.name github-actions | |
| git config user.email [email protected] | |
| git add versions.json index.md | |
| git commit -m 'Update versions.json' || exit 0 | |
| git push |